home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 011a / ripscrip.zip / RIPSCRIP.DOC
Text File  |  1993-01-23  |  159KB  |  3,679 lines
  1.  
  2.  
  3.                    ------------------------------------------
  4.                     RIPscrip Graphics Protocol Specification
  5.  
  6.                            "Remote Imaging Protocol"
  7.  
  8.                      Written by Jeff Reeder and Mark Hayton
  9.                    Copyright (c) 1992-1993, TeleGrafix Corporation
  10.                               All Rights Reserved
  11.  
  12.                                  Revision 1.50
  13.  
  14.                               January 18th, 1993
  15.                    ------------------------------------------
  16.                        with editing by Bob Stein, 10/10/92
  17.  
  18.  
  19.  
  20.  
  21.      =====================================================================
  22.      ==                           INTRODUCTION                          ==
  23.      =====================================================================
  24.  
  25.      As system operators of many bulletin board systems, we've often
  26.      wished for some form of Graphical User Interface for our boards. Like
  27.      most Sysops, we've come across many solutions.  But they all seemed
  28.      to fall short in one way or another:  inadequate for THIS system,
  29.      incomplete, difficult to implement, too complex, or lacking in
  30.      graphics development tools.  In short, we became frustrated.
  31.  
  32.      So, we decided to write our own Graphical Script Language.
  33.  
  34.      RIPscrip stands for "Remote Imaging Protocol Script" language.  This
  35.      graphical language is our answer to the graphics needs of the BBS
  36.      community and has serious tools for implementation and practical use.
  37.  
  38.      For more information on RIPaint, RIPterm or RIPscrip development
  39.      tools, contact:
  40.  
  41.           TeleGrafix Corporation
  42.           16458 Bolsa Chica, #15
  43.           Huntington Beach, CA 92649
  44.  
  45.           VOICE: (714) 846-4179
  46.           FAX  : (714) 846-4189
  47.           DATA : (714) 840-3520 (ArenaBBS: The Major BBS...32 lines)
  48.  
  49.  
  50.  
  51.           ResNova Software
  52.           16458 Bolsa Chica, #193
  53.           Huntington Beach, CA 92649
  54.  
  55.           VOICE: (714) 840-6082
  56.           FAX  : (714) 840-0488
  57.           DATA : (714) 840-8641 (Nova Central: Nova Link Pro...4 lines)
  58.  
  59.  
  60.  
  61.           RIP Demo Midwest
  62.  
  63.           VOICE: (708) 820-8875
  64.           DATA : (708) 978-2777 (RIP Demo Midwest BBS: TBBS...2 lines)
  65.           FAX  : (708) 898-4994
  66.  
  67.  
  68.  
  69.      =====================================================================
  70.      ==                            DEFINITION                           ==
  71.      =====================================================================
  72.  
  73.      RIPscrip is a text based Script language for displaying online
  74.      graphics.  The script language conforms to 7-bit ASCII, avoiding the
  75.      use of Extended ASCII characters.  This allows transmission over X.25
  76.      networks and other carriers that do not support full 8-bit binary
  77.      transfers easily.  RIPscrip allows RIPscrip graphical statements to
  78.      be mixed with printable ASCII text and [de facto standard]
  79.      ANSI/VT-100 directives.  RIPscrip can dynamically determine what is
  80.      graphics and what is text and display them appropriately in separate
  81.      windows (a graphics window and a text window).  And if you must have
  82.      your own proprietary commands, RIPscrip has room for that too.
  83.  
  84.  
  85.  
  86.  
  87.  
  88.      =====================================================================
  89.      ==                     HOW DOES RIPscrip WORK?                     ==
  90.      =====================================================================
  91.  
  92.      RIPscrip uses a flexible, and very efficient script language for its
  93.      graphical statements.  Its efficiency stems from its compactness and
  94.      developmental planning.  It is entirely Object Oriented instead of
  95.      Raster Oriented for efficient transmission of data and powerful
  96.      editing capabilities (using RIPaint for example).  The language is
  97.      open ended enough so that literally trillions of different graphics
  98.      commands can be implemented as needed.  RIPscrip is not a proprietary
  99.      protocol standard and is open to suggestion from the rest of the
  100.      world.
  101.  
  102.      Earlier Graphical Script Languages (Avatar and Skypix among others),
  103.      utilize special command characters to indicate which graphics command
  104.      is to be executed.  This precludes their use on systems that are
  105.      limited to ASCII printable text.  Traditional script languages use
  106.      English words to accomplish things (eg, "BOX 0,0 100,50").  This kind
  107.      of thing is incredibly bulky, especially when you consider that
  108.      pictures are usually not simple things, but comprised of hundreds or
  109.      thousands of individual graphical operations (eg, line, circles,
  110.      fills, text, etc.).  With this in mind, a human-readable script
  111.      language was completely inappropriate for the relatively limited
  112.      bandwidth of conventional modems.
  113.  
  114.      So, one of our main strategies for this language was to make it as
  115.      efficient as possible without going completely binary.  This allows
  116.      the immediate installation of the protocol onto any ASCII text-based
  117.      host system -- because the language consists entirely of ASCII
  118.      printable characters.  We justify the unreadability of the language
  119.      by pointing out the limitations of today's modems and phone lines --
  120.      the language must be compact.
  121.  
  122.  
  123.  
  124.  
  125.      =====================================================================
  126.      ==              RIPscrip PROTOCOL - GENERAL STRUCTURE              ==
  127.      =====================================================================
  128.  
  129.      This document describes RIPscrip commands and functions supported
  130.      with RIPterm v1.02.
  131.  
  132.      RIPscrip is organized into 10 levels of graphical commands (low
  133.      Level-0 to high Level-9).  Level-0 commands are the building blocks
  134.      of RIPscrip.  The basic graphics primitives of the system are all
  135.      Level-0, including the commands LINE, RECTANGLE, CIRCLE, COLOR, FONT,
  136.      etc.  Each level of RIPscrip gets progressively higher-level in
  137.      concept.  For example, Level-1 commands use Mouse Regions, Icons, and
  138.      Formatted Text Regions.
  139.  
  140.      The basic Syntax Rules are as follows:
  141.  
  142.           1.  A RIPscrip command line starts at the beginning of a
  143.               line of text.  A RIPscrip command line moved to the
  144.               middle of a line of text is treated as literal text.
  145.               This prevents people inserting mischievous things in
  146.               teleconference messages, or similar pranks.  The only
  147.               exception to this rule is stated below under item 6,
  148.               "continuation of long lines".
  149.  
  150.           2.  A RIPscrip command line begins with an exclamation
  151.               mark (!)
  152.  
  153.           3.  Every RIPscrip command is preceded by the universal
  154.               RIPscrip delimiter, vertical-bar (|)
  155.  
  156.           4.  Individual RIPscrip commands may be combined on the
  157.               same line providing they are separated by the
  158.               vertical bar delimiter.
  159.  
  160.           5.  RIPscrip commands or command lines may be split across
  161.               multiple lines with a backslash (\) just before each
  162.               split.  This helps RIPscrip commands conform to right
  163.               margins and escape word wrapping.  An example:
  164.  
  165.                    !|c02|L02030405|P0901020102010201020102\
  166.                    0102010201020102
  167.  
  168.           6.  RIPscrip must allow for normal text to be inter-mixed
  169.               with RIPscrip commands.  If unrecognized text appears
  170.               after a RIPscrip command, on the same line, the text
  171.               is ignored (the command is not ignored).  A line that
  172.               does not begin with "!|" is considered raw text and is
  173.               routed to the TTY text window (see "8" below).
  174.  
  175.           7.  RIPscrip makes provisions for a GRAPHICAL WINDOW and a
  176.               TEXT WINDOW.  The Graphical Window is where all
  177.               RIPscrip graphics appear.  the TEXT WINDOW is where
  178.               raw text appears.  Raw Text includes ANSI color and
  179.               cursor movement codes (a subset of VT-100 terminal
  180.               emulation).
  181.  
  182.           8.  The vertical bar (|) of a RIPscrip command can be
  183.               followed by an level number.  If the 1st character
  184.               after (|) is a numeric digit (1-9), then that's the
  185.               RIPscrip Command Level.  If the very 1st character is
  186.               NOT a digit 1-9, then it is the command type character
  187.               and the command is a Level-0 command.  If the 1st
  188.               character is a digit 1-9, and the second character is
  189.               also a digit, then that defines a sub-level of a
  190.               RIPscrip level.  For example:
  191.  
  192.                  !|L ..... RIPscrip Level-0 Command "L"
  193.                  !|1L .... RIPscrip Level-1 Command "L"
  194.                  !|15L ... RIPscrip Level-1, sub-level 5 Command "L"
  195.  
  196.               Each of the above examples are unique commands not to
  197.               be confused with each other.  You may continue the
  198.               sub-levels up to a maximum level of 10 (eg,
  199.               !|1234567890<cmd>").
  200.  
  201.           9.  Every RIPscrip command includes a command type
  202.               character.  In Level-0 commands, this character
  203.               immediately follows the vertical bar.  At all other
  204.               levels, it follows the level digits.  The command type
  205.               character may be any printable non-decimal-digit
  206.               character.
  207.  
  208.          10.  Following the command type character are 0 or more
  209.               parameters.  If the command requires a text-string, it
  210.               is always the LAST parameter.  Numeric parameters DO
  211.               NOT have any delimiters (commas, dashes, spaces,
  212.               etc).  A variable width numeric parameter may be used
  213.               as the last parameter.  This allows for maximum
  214.               efficiency.  Numbers are represented in base-36.  This
  215.               compacts numbers down to roughly 3/5 of their decimal
  216.               form.  This numbering system, technically called
  217.               "Hexa-Tri-Decimal", has affectionately been dubbed
  218.               "MegaNums".  Unlike Hexadecimal which uses 0-9, A-F,
  219.               MegaNums take advantage of the entire alphabet, using
  220.               characters 0-9 and A-Z.
  221.  
  222.          11.  An exclamation mark (!) or vertical bar (|) character
  223.               can appear in a RIPscrip text parameter by preceding
  224.               it with a backslash(\).  A literal backslash is
  225.               represented with a double-backslash (\\).
  226.  
  227.          12.  A RIPscrip sequence CAN begin in a column other than
  228.               column #0, if the exclamation mark introducer is
  229.               replaced with a CTRL-A (Start of Header SOH) character.
  230.               Since 99.9% of all BBS'es do not allow Users to enter
  231.               most control characters, users will be unable to begin
  232.               RIPscrip sequences in the middle of a command line.
  233.               Only the Host should be able to do this.  This prevents
  234.               people from cluttering teleconference, or other areas
  235.               of a Host with spurious RIPscrip sequences.
  236.  
  237.  
  238.  
  239.  
  240.  
  241.      =====================================================================
  242.      ==                    RIPscrip COMMAND REFERENCE                   ==
  243.      =====================================================================
  244.  
  245.      The remainder of this document details the RIPscrip command set.
  246.      Each command has these aspects:
  247.  
  248.          SYMBOL - the symbolic constant that is referenced in the
  249.                   RIPscrip API Library code.  This is  the universal
  250.                   name for the command.
  251.  
  252.           LEVEL - The Command Level.  Sub-levels are represented
  253.                   with decimal points (eg, 1.3.5 for Level-1,
  254.                   Sub-level 3, Sub-Sub-level 5).  This is for
  255.                   discussion purposes only.  The decimal points
  256.                   are never part of the actual command.
  257.  
  258.         COMMAND - The command type character identifying the
  259.                   command
  260.  
  261.       ARGUMENTS - The arguments or parameters for the command.
  262.                   Commands that do not require any arguments
  263.                   after the command type character are shown
  264.                   here as "<none>".  Each argument is shown in
  265.                   the order it appears in the command, and is
  266.                   represented by a name.  If an argument is
  267.                   numeric, it is followed by a width specifier
  268.                   indicating how many MegaNum digits the
  269.                   argument consists of.  (eg, ":2" means a
  270.                   2-digit MegaNum, or a value between 0 and
  271.                   1295).  If an argument does not have a width
  272.                   specifier, it is by default a text argument,
  273.                   and should be the last argument on the line.
  274.                   If a command is variable length (see POLYGON),
  275.                   then it will appear with ellipses (...)
  276.  
  277.          FORMAT - This represents the format of the command, with
  278.                   the starting "!|", the level digits, the
  279.                   command type character, and the argument list,
  280.                   with the argument names in angle brackets.
  281.                   (These arguments are spaced apart, but these
  282.                   spaces never appear in the physical commands.)
  283.  
  284.         EXAMPLE - An actual example of the RIPscrip command.
  285.  
  286.      DRAW COLOR - If YES, then this command uses or affects the
  287.                   current Drawing Color.
  288.  
  289.      LINE PATRN - If YES, then this command uses or affects the
  290.                   current Line Style Pattern.
  291.  
  292.      LINE THICK - If YES, then this command uses or affects the
  293.                   current Line Style Thickness
  294.  
  295.      FILL COLOR - If YES, then this command uses or affects the
  296.                   current Fill Color.
  297.  
  298.      FILL PATRN - If YES, then this command uses or affects the
  299.                   current Fill Pattern.
  300.  
  301.      WRITE MODE - If YES, then this command will take advantage
  302.                   of the current Write Mode (eg, COPY, or XOR).
  303.  
  304.      FONT SIZES - If YES, then this command uses or affects the
  305.                   current Font Size.
  306.  
  307.  
  308.  
  309.  
  310.  
  311.      ---------------------------------------------------------------------
  312.      Define the size and location of the TTY Text Window
  313.      ---------------------------------------------------------------------
  314.                Symbol: RIP_TEXT_WINDOW
  315.                 Level: 0
  316.               Command: w
  317.             Arguments: x0:2, y0:2, x1:2, y1:2, wrap:1, size:1
  318.                Format: !|w <x0> <y0> <x1> <y1> <wrap> <size>
  319.               Example: !|w00001B0M10
  320.       Uses Draw Color: NO
  321.       Uses Line Patrn: NO
  322.       Uses Line Thick: NO
  323.       Uses Fill Color: NO
  324.       Uses Fill Patrn: NO
  325.       Uses Write Mode: NO
  326.       Uses Font Sizes: NO
  327.  
  328.      This command specifies the dimensions of the virtual TTY window that
  329.      will display all ASCII/ANSI (non-RIPscrip) data coming across the
  330.      connection.  (x0,y0) defines the upper-left corner of the window in
  331.      text-based character-cell coordinates.  (x1,y1) defines the
  332.      lower-right corner of the window (inclusive).  There may be two
  333.      simultaneous windows on the screen, one for TTY text, and one for the
  334.      display of RIPscrip graphics (a viewport), and they may overlap.
  335.  
  336.      Bytes received over the modem are first checked for RIPscrip
  337.      commands.  All bytes that don't conform to the RIPscrip syntax are
  338.      treated as ANSI/ASCII and displayed in the TTY window (if defined).
  339.      User keystrokes that are echoed by the BBS would also appear in the
  340.      text window by this scheme.
  341.  
  342.      The text window may be made invisible, ignoring all non-RIPscrip
  343.      bytes, by setting all RIP_TEXT_WINDOW parameters to zero (0).  The X
  344.      and Y parameters ranges vary depending on the setting of the <size>
  345.      parameter which governs the font size used for the output text. Valid
  346.      settings for the <size> parameter and the ranges for X/Y values are
  347.      as follows:
  348.  
  349.           size   Font Size    X Range   Y Range
  350.           ---------------------------------------
  351.            0       8x8         0-79      0-42
  352.            1       7x7         0-91      0-49
  353.            2       8x14        0-79      0-24
  354.            3       7x14        0-91      0-24
  355.            4       16x14       0-39      0-24
  356.  
  357.      The <wrap> parameter applies to both the horizontal and vertical
  358.      dimensions.  If <wrap> is set to 1, then any text that extends beyond
  359.      the right margin of the window will wrap to the next line of the
  360.      window, scrolling the window up if necessary.  If <wrap> is 0, then
  361.      any text going beyond the right margin is truncated and no scrolling
  362.      is performed; the cursor remains at the right margin.
  363.  
  364.  
  365.  
  366.  
  367.  
  368.      ---------------------------------------------------------------------
  369.      Define the size and location of the Graphics Window
  370.      ---------------------------------------------------------------------
  371.                Symbol: RIP_VIEWPORT
  372.                 Level: 0
  373.               Command: v
  374.             Arguments: x0:2, y0:2, x1:2, y1:2
  375.                Format: !|v <x0> <y0> <x1> <y1>
  376.               Example: !|v00002E1M
  377.       Uses Draw Color: NO
  378.       Uses Line Patrn: NO
  379.       Uses Line Thick: NO
  380.       Uses Fill Color: NO
  381.       Uses Fill Patrn: NO
  382.       Uses Write Mode: NO
  383.       Uses Font Sizes: NO
  384.  
  385.      This command defines the (X,Y) pixel boundaries of the RIPscrip
  386.      graphics window, which will contain all RIPscrip graphics output.
  387.      ASCII/ANSI text will be displayed in the virtual TTY window defined
  388.      by the RIP_TEXT_WINDOW command above.  (x0,y0) defines the upper-left
  389.      corner of the graphics viewport, and (x1,y1) defines the lower-right
  390.      corner (inclusive).  The viewport may be disabled, so RIPscrip
  391.      graphics commands are ignored, by setting all parameters to zero (0).
  392.  
  393.      Graphics displayed in the viewport is "truncated" at this rectangular
  394.      border, meaning if a circle would normally extend outside one of the
  395.      borders, it will be chopped, only displaying the portion of the
  396.      circle that is contained inside the viewport boundaries.
  397.  
  398.      Coordinates are specified based on a 640x350 pixel resolution, meaning
  399.      X can be anywhere from 0 - 639, and Y can be anywhere from 0 - 349.
  400.      x0 must be less than x1 and y0 must be less than y1 unless all
  401.      parameters are set to zero, indicating that the graphics window is
  402.      disabled.
  403.  
  404.  
  405.  
  406.  
  407.  
  408.      ---------------------------------------------------------------------
  409.      Reset & Clear Graphics and Text Windows to full screen
  410.      ---------------------------------------------------------------------
  411.                Symbol: RIP_RESET_WINDOWS
  412.                 Level: 0
  413.               Command: *
  414.             Arguments: <none>
  415.                Format: !|*
  416.               Example: !|*
  417.       Uses Draw Color: NO
  418.       Uses Line Patrn: NO
  419.       Uses Line Thick: NO
  420.       Uses Fill Color: NO
  421.       Uses Fill Patrn: NO
  422.       Uses Write Mode: NO
  423.       Uses Font Sizes: NO
  424.  
  425.      This command will set the Text Window to a full 80x43 EGA hi-res text
  426.      mode, place the cursor in the upper left corner, clear the screen,
  427.      and zoom the Graphics Window to full 640x350 EGA screen.  Both
  428.      windows are filled with the current graphics background color.  Also,
  429.      all Mouse Regions are deleted and the Clipboard is erased.  A system
  430.      might use this function before entering a text only mode that does
  431.      not support RIP commands.  This command will also restore the default
  432.      16-color RIP palette (see RIP_SET_PALETTE below).
  433.  
  434.  
  435.  
  436.  
  437.  
  438.      ---------------------------------------------------------------------
  439.      Clears the Text Window to the current background color
  440.      ---------------------------------------------------------------------
  441.                Symbol: RIP_ERASE_WINDOW
  442.                 Level: 0
  443.               Command: e
  444.             Arguments: <none>
  445.                Format: !|e
  446.               Example: !|e
  447.       Uses Draw Color: NO
  448.       Uses Line Patrn: NO
  449.       Uses Line Thick: NO
  450.       Uses Fill Color: NO
  451.       Uses Fill Patrn: NO
  452.       Uses Write Mode: NO
  453.       Uses Font Sizes: NO
  454.  
  455.      This clears the TTY text window to the current graphics background
  456.      color and positions the cursor in the upper-left corner of the
  457.      window.  If the text window is inactive, then this command is
  458.      ignored.  If the text and graphics windows overlap, then this command
  459.      will clear the overlapping portion also.
  460.  
  461.  
  462.  
  463.  
  464.  
  465.      ---------------------------------------------------------------------
  466.      Clears the Graphics Window to the current background color
  467.      ---------------------------------------------------------------------
  468.                Symbol: RIP_ERASE_VIEW
  469.                 Level: 0
  470.               Command: E
  471.             Arguments: <none>
  472.                Format: !|E
  473.               Example: !|E
  474.       Uses Draw Color: NO
  475.       Uses Line Patrn: NO
  476.       Uses Line Thick: NO
  477.       Uses Fill Color: NO
  478.       Uses Fill Patrn: NO
  479.       Uses Write Mode: NO
  480.       Uses Font Sizes: NO
  481.  
  482.      This command clears the Graphics Viewport to the current graphics
  483.      background color.  If the graphics viewport is not active (if the
  484.      boundaries are 0,0,0,0), then this command is ignored.  If the text
  485.      and graphics windows overlap, then this command will clear the
  486.      overlapping portion also.
  487.  
  488.  
  489.  
  490.  
  491.  
  492.      ---------------------------------------------------------------------
  493.      Move the Text (TTY) cursor to given row & column in the text window
  494.      ---------------------------------------------------------------------
  495.                Symbol: RIP_GOTOXY
  496.                 Level: 0
  497.               Command: g
  498.             Arguments: x:2, y:2
  499.                Format: !|g <x> <y>
  500.               Example: !|g0509
  501.       Uses Draw Color: NO
  502.       Uses Line Patrn: NO
  503.       Uses Line Thick: NO
  504.       Uses Fill Color: NO
  505.       Uses Fill Patrn: NO
  506.       Uses Write Mode: NO
  507.       Uses Font Sizes: NO
  508.  
  509.      This command sets the position of the text cursor in the TTY Text
  510.      window, if it is active.  If inactive (if the dimensions are
  511.      0,0,0,0), then this command is ignored.  This command is equivalent
  512.      to the ANSI/VT-100 command goto x/y, <Esc>[x;yH, except that the
  513.      coordinates of that ANSI command are 1-based and the coordinates of
  514.      this RIPscrip command are 0-based.
  515.  
  516.  
  517.  
  518.  
  519.  
  520.      ---------------------------------------------------------------------
  521.      Move the cursor to the Upper-Left corner of the Text Window
  522.      ---------------------------------------------------------------------
  523.                Symbol: RIP_HOME
  524.                 Level: 0
  525.               Command: H
  526.             Arguments: <none>
  527.                Format: !|H
  528.               Example: !|H
  529.       Uses Draw Color: NO
  530.       Uses Line Patrn: NO
  531.       Uses Line Thick: NO
  532.       Uses Fill Color: NO
  533.       Uses Fill Patrn: NO
  534.       Uses Write Mode: NO
  535.       Uses Font Sizes: NO
  536.  
  537.      This command positions the text cursor to the upper-left corner in
  538.      the TTY Text Window, if it is active.
  539.  
  540.  
  541.  
  542.  
  543.  
  544.      ---------------------------------------------------------------------
  545.      Erase the current text line from the cursor to the end of line
  546.      ---------------------------------------------------------------------
  547.                Symbol: RIP_ERASE_EOL
  548.                 Level: 0
  549.               Command: >
  550.             Arguments: <none>
  551.                Format: !|>
  552.               Example: !|>
  553.       Uses Draw Color: NO
  554.       Uses Line Patrn: NO
  555.       Uses Line Thick: NO
  556.       Uses Fill Color: NO
  557.       Uses Fill Patrn: NO
  558.       Uses Write Mode: NO
  559.       Uses Font Sizes: NO
  560.  
  561.      This command will erase the current text line in the TTY text window
  562.      from the current cursor location (inclusive) to the end of the line.
  563.      The erased region is filled with the current graphics background
  564.      color.  This differs from the ANSI command ESC[K which clears the
  565.      area with the current ANSI background color.
  566.  
  567.  
  568.  
  569.  
  570.  
  571.      ---------------------------------------------------------------------
  572.      Set the current drawing color for graphics primitives
  573.      ---------------------------------------------------------------------
  574.                Symbol: RIP_COLOR
  575.                 Level: 0
  576.               Command: c
  577.             Arguments: color:2
  578.                Format: !|c <color>
  579.               Example: !|cA
  580.       Uses Draw Color: YES
  581.       Uses Line Patrn: NO
  582.       Uses Line Thick: NO
  583.       Uses Fill Color: NO
  584.       Uses Fill Patrn: NO
  585.       Uses Write Mode: NO
  586.       Uses Font Sizes: NO
  587.  
  588.      This command sets the color for drawing lines, circles, arcs,
  589.      rectangles, and other graphics primitives, as well as the color for
  590.      drawing grahics-text from the RIP_TEXT class of commands (not from
  591.      ASCII/ANSI text).  This command does not affect Fill colors or Fill
  592.      Patterns (see below).  It does affect the borders of graphic objects,
  593.      for example the border of an ellipse drawn with the RIP_FILLED_OVAL
  594.      command.  (The interior of the ellipse would be drawn according to
  595.      the most recent RIP_FILL_STYLE command.)
  596.  
  597.      This command chooses one of the colors of the 16-color RIP palette
  598.      defined by the RIP_SET_PALETTE command.  Here is the default 16-color
  599.      RIP palette:
  600.  
  601.           VALUE ... COLOR
  602.           -------------------------------------
  603.             00  ... Black (00 is always the background color)
  604.             01  ... Blue
  605.             02  ... Green
  606.             03  ... Cyan
  607.             04  ... Red
  608.             05  ... Magenta
  609.             06  ... Brown
  610.             07  ... Light Gray
  611.             08  ... Dark Gray
  612.             09  ... Light Blue
  613.             0A  ... Light Green
  614.             0B  ... Light Cyan
  615.             0C  ... Light Red
  616.             0D  ... Light Magenta
  617.             0E  ... Yellow
  618.             0F  ... White
  619.  
  620.  
  621.  
  622.  
  623.  
  624.      ---------------------------------------------------------------------
  625.      Set the 16-color RIP palette from the master 64-color EGA palette
  626.      ---------------------------------------------------------------------
  627.                Symbol: RIP_SET_PALETTE
  628.                 Level: 0
  629.               Command: Q
  630.             Arguments: c1:2, c2:2, ... c16:2
  631.                Format: !|Q <c1> <c2> ... <c16>
  632.               Example: !|Q000102030405060708090A0B0C0D0E0F
  633.       Uses Draw Color: YES
  634.       Uses Line Patrn: NO
  635.       Uses Line Thick: NO
  636.       Uses Fill Color: NO
  637.       Uses Fill Patrn: NO
  638.       Uses Write Mode: NO
  639.       Uses Font Sizes: NO
  640.  
  641.      This command modifies the 16-color RIP palette by choosing from the
  642.      64 colors in the master EGA palette.  This allows you to alter the
  643.      colors in your RIPscrip graphics scenes.  Once a Set Palette command
  644.      is processed, any colors on the screen that had their corresponding
  645.      palette entries changed will instantly switch to the new color set.
  646.      You may obtain color "cycling" effects by using this command.  The
  647.      default 16-color RIP palette is always restored when a
  648.      RIP_RESET_WINDOWS command is encountered.  The default 16-color RIP
  649.      palette is as follows:
  650.  
  651.                            MASTER
  652.           16-COLOR         64-COLOR
  653.           RIP PALETTE      EGA PALETTE
  654.           COLOR-CODE       COLOR-CODE    COLOR
  655.           -------------------------------------------------------
  656.               00            0  (00)      Black
  657.               01            1  (01)      Blue
  658.               02            2  (02)      Green
  659.               03            3  (03)      Cyan
  660.               04            4  (04)      Red
  661.               05            5  (05)      Magenta
  662.               06            7  (06)      Brown
  663.               07            20 (0K)      Light Gray
  664.               08            56 (1K)      Dark Gray
  665.               09            57 (1L)      Light Blue
  666.               0A            58 (1M)      Light Green
  667.               0B            59 (1N)      Light Cyan
  668.               0C            60 (1O)      Light Red
  669.               0D            61 (1P)      Light Magenta
  670.               0E            62 (1Q)      Yellow
  671.               0F            63 (1R)      White
  672.  
  673.      Color 00 of the 16-color RIP palette is always the background color
  674.      (which is typically Black, or color 00 of the 64-color EGA palette).
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.      ---------------------------------------------------------------------
  682.      Set one color of the 16-color RIP palette from the Master Palette
  683.      ---------------------------------------------------------------------
  684.                Symbol: RIP_ONE_PALETTE
  685.                 Level: 0
  686.               Command: a
  687.             Arguments: color:2 value:2
  688.                Format: !|a <color> <value>
  689.               Example: !|a051B
  690.       Uses Draw Color: YES
  691.       Uses Line Patrn: NO
  692.       Uses Line Thick: NO
  693.       Uses Fill Color: NO
  694.       Uses Fill Patrn: NO
  695.       Uses Write Mode: NO
  696.       Uses Font Sizes: NO
  697.  
  698.      This command modifies one color in the 16-color RIP palette.  The
  699.      Color number is sent along with the a color value from the Master
  700.      Color Palette to set the new color to.  The color <value> must be
  701.      in the range of 0-63 to allow access to the 64 colors in the master
  702.      EGA palette.  This allows you to alter the colors in your RIPscrip
  703.      graphics scenes.  Once a Set One Palette command is processed, any
  704.      colors on the screen that correspond to the <color> number will be
  705.      changed instantly to the new color value.  You may obtain color
  706.      "cycling" effects by using this command.  The default 16-color RIP
  707.      palette is always restored when a RIP_RESET_WINDOWS command is
  708.      encountered.  The default 16-color RIP palette is as follows:
  709.  
  710.                            MASTER
  711.           16-COLOR         64-COLOR
  712.           RIP PALETTE      EGA PALETTE
  713.           COLOR-CODE       COLOR-CODE    COLOR
  714.           -------------------------------------------------------
  715.               00            0  (00)      Black
  716.               01            1  (01)      Blue
  717.               02            2  (02)      Green
  718.               03            3  (03)      Cyan
  719.               04            4  (04)      Red
  720.               05            5  (05)      Magenta
  721.               06            7  (06)      Brown
  722.               07            20 (0K)      Light Gray
  723.               08            56 (1K)      Dark Gray
  724.               09            57 (1L)      Light Blue
  725.               0A            58 (1M)      Light Green
  726.               0B            59 (1N)      Light Cyan
  727.               0C            60 (1O)      Light Red
  728.               0D            61 (1P)      Light Magenta
  729.               0E            62 (1Q)      Yellow
  730.               0F            63 (1R)      White
  731.  
  732.      Color 00 of the 16-color RIP palette is always the background color
  733.      (which is typically Black, or color 00 of the 64-color EGA palette).
  734.  
  735.  
  736.  
  737.  
  738.  
  739.      ---------------------------------------------------------------------
  740.      Set Drawing Mode for graphics primitives
  741.      ---------------------------------------------------------------------
  742.                Symbol: RIP_WRITE_MODE
  743.                 Level: 0
  744.               Command: W
  745.             Arguments: mode:2
  746.                Format: !|W <mode>
  747.               Example: !|W00
  748.       Uses Draw Color: NO
  749.       Uses Line Patrn: NO
  750.       Uses Line Thick: NO
  751.       Uses Fill Color: NO
  752.       Uses Fill Patrn: NO
  753.       Uses Write Mode: YES
  754.       Uses Font Sizes: NO
  755.  
  756.      This command sets the current drawing mode for most of the graphics
  757.      primitives:
  758.  
  759.           mode = 00 ... Normal drawing mode (overwrite)
  760.                = 01 ... XOR (complimentary) mode
  761.  
  762.      In normal mode, things are drawn in the current drawing color over
  763.      top of whatever is in the graphics viewport.  This is the typical
  764.      mode of operation in a GUI environment.
  765.  
  766.      In the XOR mode, instead of changing each pixel to the current
  767.      drawing color, the pixel is inverted (black changes to white, red to
  768.      green, etc.).  Drawing the same item a second time erases it
  769.      completely.  This mode is useful for drawing something temporarily,
  770.      or for animation.  The Rubber Band mode of most paint programs uses a
  771.      mode like this.
  772.  
  773.  
  774.  
  775.  
  776.  
  777.      ---------------------------------------------------------------------
  778.      Move the current drawing position to (X,Y)
  779.      ---------------------------------------------------------------------
  780.                Symbol: RIP_MOVE
  781.                 Level: 0
  782.               Command: m
  783.             Arguments: x:2, y:2
  784.                Format: !|m <x> <y>
  785.               Example: !|m0509
  786.       Uses Draw Color: NO
  787.       Uses Line Patrn: NO
  788.       Uses Line Thick: NO
  789.       Uses Fill Color: NO
  790.       Uses Fill Patrn: NO
  791.       Uses Write Mode: NO
  792.       Uses Font Sizes: NO
  793.  
  794.      This command moves the current graphics drawing cursor to (x,y).  You
  795.      could use this to draw text at a certain point, but you'd probably
  796.      use RIP_TEXT_XY instead.  This command is primarily provided for
  797.      future development which will make use of its ability to relocate the
  798.      current drawing position without physically drawing anything.
  799.  
  800.  
  801.  
  802.  
  803.  
  804.      ---------------------------------------------------------------------
  805.      Draw Text in current Font/Size/Color at current location
  806.      ---------------------------------------------------------------------
  807.                Symbol: RIP_TEXT
  808.                 Level: 0
  809.               Command: T
  810.             Arguments: text-string
  811.                Format: !|T <text-string>
  812.               Example: !|Thello world
  813.       Uses Draw Color: YES
  814.       Uses Line Patrn: NO
  815.       Uses Line Thick: NO
  816.       Uses Fill Color: NO
  817.       Uses Fill Patrn: NO
  818.       Uses Write Mode: YES
  819.       Uses Font Sizes: YES
  820.  
  821.      This command displays text at the current location in the graphics
  822.      window, as set with the RIP_MOVE command.  The text is also affected
  823.      by the most recent settings of these commands:
  824.  
  825.           RIP_FONT_STYLE - font style (character set, direction, size)
  826.           RIP_WRITE_MODE - drawing mode (normal or XOR)
  827.           RIP_COLOR      - drawing color (from the 16-color RIP palette)
  828.  
  829.      The drawing position is placed at the end of the last character
  830.      drawn.
  831.  
  832.      The current drawing position is set immediately to the right of the
  833.      drawn text.  Subsequent Line, Circle or other such commands will not
  834.      affect this position.  This provides a means so that you can quickly
  835.      do another RIP_TEXT command (presumably in another color) at a later
  836.      time and have the text show up immediately after the previous text.
  837.  
  838.  
  839.  
  840.  
  841.  
  842.      ---------------------------------------------------------------------
  843.      Draw Text in current Font/Size/Color at specific location
  844.      ---------------------------------------------------------------------
  845.                Symbol: RIP_TEXT_XY
  846.                 Level: 0
  847.               Command: @
  848.             Arguments: x:2, y:2 and text-string
  849.                Format: !|@ <x> <y> <text-string>
  850.               Example: !|@0011hello world
  851.       Uses Draw Color: YES
  852.       Uses Line Patrn: NO
  853.       Uses Line Thick: NO
  854.       Uses Fill Color: NO
  855.       Uses Fill Patrn: NO
  856.       Uses Write Mode: YES
  857.       Uses Font Sizes: YES
  858.  
  859.      This command is an efficient combination of RIP_MOVE and RIP_TEXT.
  860.      The text is drawn at the specified location according to the same
  861.      settings as apply to RIP_TEXT (see above).
  862.  
  863.      The current drawing position is set immediately to the right of the
  864.      drawn text.  Subsequent Line, Circle or other such commands will not
  865.      affect this position.  This provides a means so that you can quickly
  866.      do another RIP_TEXT command (presumably in another color) at a later
  867.      time and have the text show up immediately after the previous text.
  868.  
  869.  
  870.  
  871.  
  872.  
  873.      ---------------------------------------------------------------------
  874.      Select the current Font Style, Orientation and Size
  875.      ---------------------------------------------------------------------
  876.                Symbol: RIP_FONT_STYLE
  877.                 Level: 0
  878.               Command: Y
  879.             Arguments: font:2, direction:2, size:2, res:2
  880.                Format: !|Y <font> <direction> <size> <res>
  881.               Example: !|Y01000400
  882.       Uses Draw Color: NO
  883.       Uses Line Patrn: NO
  884.       Uses Line Thick: NO
  885.       Uses Fill Color: NO
  886.       Uses Fill Patrn: NO
  887.       Uses Write Mode: NO
  888.       Uses Font Sizes: YES
  889.  
  890.      This command sets the current font, direction and size for subsequent
  891.      RIP_TEXT commands.
  892.  
  893.           FONT
  894.           ---------------------------------------------------------
  895.           00 ... Default 8x8 font (bit-mapped)
  896.           01 ... Triplex Font (scalable)
  897.           02 ... Small Font (scalable)
  898.           03 ... Sans Serif Font (scalable)
  899.           04 ... Gothic [old English] Font (scalable)
  900.  
  901.           DIRECTION
  902.           ---------------------------------------------------------
  903.           00 ... Horizontal direction
  904.           01 ... Vertical direction
  905.  
  906.           SIZE
  907.           ---------------------------------------------------------
  908.           01 ... Normal, default size
  909.           02 ... Magnification factor  2 ( x2)
  910.           03 ... Magnification factor  3 ( x3)
  911.           04 ... Magnification factor  4 ( x4)
  912.           05 ... Magnification factor  5 ( x5)
  913.           06 ... Magnification factor  6 ( x6)
  914.           07 ... Magnification factor  7 ( x7)
  915.           08 ... Magnification factor  8 ( x8)
  916.           09 ... Magnification factor  9 ( x9)
  917.           0A ... Magnification factor 10 (x10)
  918.  
  919.      NOTE:  The Default 8x8 font is bit-mapped and appears best when drawn
  920.      with size=1.  If you use a size greater than one, the individual
  921.      pixels making up the font are magnified, giving a jagged look.  This
  922.      may or may not be a desirable effect.  The Scalable Fonts (1-4) are
  923.      smooth scalable "vector" fonts.  The two byte <res> parameter is a
  924.      RESERVED parameter that is intended for future development.
  925.  
  926.  
  927.  
  928.  
  929.  
  930.      ---------------------------------------------------------------------
  931.      Draws a single pixel on the screen using current drawing color
  932.      ---------------------------------------------------------------------
  933.                Symbol: RIP_PIXEL
  934.                 Level: 0
  935.               Command: X
  936.             Arguments: x:2, y:2
  937.                Format: !|X <x> <y>
  938.               Example: !|X1122
  939.       Uses Draw Color: YES
  940.       Uses Line Patrn: NO
  941.       Uses Line Thick: NO
  942.       Uses Fill Color: NO
  943.       Uses Fill Patrn: NO
  944.       Uses Write Mode: NO
  945.       Uses Font Sizes: NO
  946.  
  947.      This command will draw a single pixel in the current drawing color at
  948.      the given (x,y) graphics position.  This command is included for
  949.      completeness, but in practice it would be extremely inefficient to
  950.      make much use of it.
  951.  
  952.  
  953.  
  954.  
  955.  
  956.      ---------------------------------------------------------------------
  957.      Draw a line in the current color and line style/thickness
  958.      ---------------------------------------------------------------------
  959.                Symbol: RIP_LINE
  960.                 Level: 0
  961.               Command: L
  962.             Arguments: x0:2, y0:2, x1:2, y1:2
  963.                Format: !|L <x0> <y0> <x1> <y1>
  964.               Example: !|L00010A0E
  965.       Uses Draw Color: YES
  966.       Uses Line Patrn: YES
  967.       Uses Line Thick: YES
  968.       Uses Fill Color: NO
  969.       Uses Fill Patrn: NO
  970.       Uses Write Mode: YES
  971.       Uses Font Sizes: NO
  972.  
  973.      This command will draw a line in the current drawing color, using the
  974.      current line style, pattern and thickness.  The line is drawn from
  975.      (x0,y0) to (x1,y1) in the graphics viewport.
  976.  
  977.  
  978.  
  979.  
  980.  
  981.      ---------------------------------------------------------------------
  982.      Draw a rectangle in the current color and line style/thickness
  983.      ---------------------------------------------------------------------
  984.                Symbol: RIP_RECTANGLE
  985.                 Level: 0
  986.               Command: R
  987.             Arguments: x0:2, y0:2, x1:2, y1:2
  988.                Format: !|R <x0> <y0> <x1> <y1>
  989.               Example: !|R00010A0E
  990.       Uses Draw Color: YES
  991.       Uses Line Patrn: YES
  992.       Uses Line Thick: YES
  993.       Uses Fill Color: NO
  994.       Uses Fill Patrn: NO
  995.       Uses Write Mode: YES
  996.       Uses Font Sizes: NO
  997.  
  998.      This command draws a rectangle in the current drawing color, using
  999.      the current line style, pattern and thickness.  (x0,y0) and (x1,y1)
  1000.      are any two opposing corners of the rectangle.  If x0=x1 or y0=y1
  1001.      then the command will draw a single vertical or horizontal line.  The
  1002.      rectangle interior is not filled by RIP_RECTANGLE.
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.      ---------------------------------------------------------------------
  1009.      Draws a solid, filled rectangle using current fill color and pattern
  1010.      ---------------------------------------------------------------------
  1011.                Symbol: RIP_BAR
  1012.                 Level: 0
  1013.               Command: B
  1014.             Arguments: x0:2, y0:2, x1:2, y1:2
  1015.                Format: !|B <x0> <y0> <x1> <y1>
  1016.               Example: !|B00010A0E
  1017.       Uses Draw Color: NO
  1018.       Uses Line Patrn: NO
  1019.       Uses Line Thick: NO
  1020.       Uses Fill Color: YES
  1021.       Uses Fill Patrn: YES
  1022.       Uses Write Mode: NO
  1023.       Uses Font Sizes: NO
  1024.  
  1025.      This command fills a rectangular region with the current fill color
  1026.      and pattern.  No border is drawn.
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.      ---------------------------------------------------------------------
  1033.      Draw a circle in the current color and line thickness (no style)
  1034.      ---------------------------------------------------------------------
  1035.                Symbol: RIP_CIRCLE
  1036.                 Level: 0
  1037.               Command: C
  1038.             Arguments: x_center:2, y_center:2, radius:2
  1039.                Format: !|C <x_center> <y_center> <radius>
  1040.               Example: !|C1E180M
  1041.       Uses Draw Color: YES
  1042.       Uses Line Patrn: NO
  1043.       Uses Line Thick: YES
  1044.       Uses Fill Color: NO
  1045.       Uses Fill Patrn: NO
  1046.       Uses Write Mode: NO
  1047.       Uses Font Sizes: NO
  1048.  
  1049.      This command draws a circle in the current drawing color and line
  1050.      thickness.  The <radius> is in pixel units.  This command understands
  1051.      aspect ratios and will draw a truly circular circle instead of an
  1052.      oblong circle (ellipse) like on other graphics systems.  The aspect
  1053.      ratio is currently based on the EGA 640x350 resolution and is
  1054.      understood by both the GUI designer and the Terminal Program.  This
  1055.      command does not take advantage of line patterns, but does use the
  1056.      line thickness setting.  In other words, you can draw a circle with a
  1057.      thick or a thin border, but not a dashed or dotted border.
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.      ---------------------------------------------------------------------
  1064.      Draw an elliptical arc in the current color and line thickness
  1065.      ---------------------------------------------------------------------
  1066.                Symbol: RIP_OVAL
  1067.                 Level: 0
  1068.               Command: O
  1069.             Arguments: x:2, y:2, st_ang:2, end_ang:2, x_rad:2, y_rad:2
  1070.                Format: !|O <x> <y> <st_ang> <end_ang> <x_rad> <y_rad>
  1071.               Example: 1E1A18003G150Z
  1072.       Uses Draw Color: YES
  1073.       Uses Line Patrn: NO
  1074.       Uses Line Thick: YES
  1075.       Uses Fill Color: NO
  1076.       Uses Fill Patrn: NO
  1077.       Uses Write Mode: NO
  1078.       Uses Font Sizes: NO
  1079.  
  1080.      This command draws an elliptical arc similar to the circular RIP_ARC
  1081.      command.  The center of the ellipse is (x,y) and the arc is
  1082.      drawn starting from <st_ang> and proceeding counterclockwise to
  1083.      <end_ang> (see RIP_ARC above for details).
  1084.  
  1085.      The X radius is half the full width of the ellipse, the Y radius is
  1086.      half the full height.  The ellipse is drawn according to the current
  1087.      line thickness, but the current line pattern has no effect.
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.      ---------------------------------------------------------------------
  1094.      Draws a filled ellipse using the current fill and drawing color
  1095.      ---------------------------------------------------------------------
  1096.                Symbol: RIP_FILLED_OVAL
  1097.                 Level: 0
  1098.               Command: o
  1099.             Arguments: x_center:2, y_center:2, x_rad:2, y_rad:2
  1100.                Format: !|o <x_center> <y_center> <x_rad> <y_rad>
  1101.               Example: !|o1G2B0M0G
  1102.       Uses Draw Color: YES
  1103.       Uses Line Patrn: NO
  1104.       Uses Line Thick: YES
  1105.       Uses Fill Color: YES
  1106.       Uses Fill Patrn: YES
  1107.       Uses Write Mode: NO
  1108.       Uses Font Sizes: NO
  1109.  
  1110.      This command draws a complete filled ellipse on the screen.  The
  1111.      interior of the ellipse is drawn using the current fill pattern and
  1112.      fill color.  The outline of the ellipse is drawn using the current
  1113.      drawing color and line thickness.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.      ---------------------------------------------------------------------
  1120.      Draw a circular arc in the current color and line thickness
  1121.      ---------------------------------------------------------------------
  1122.                Symbol: RIP_ARC
  1123.                 Level: 0
  1124.               Command: A
  1125.             Arguments: x:2, y:2, start_ang:2, end_ang:2, radius:2
  1126.                Format: !|A <x> <y> <start_ang> <end_ang> <radius>
  1127.               Example: !|A1E18003G15
  1128.       Uses Draw Color: YES
  1129.       Uses Line Patrn: NO
  1130.       Uses Line Thick: YES
  1131.       Uses Fill Color: NO
  1132.       Uses Fill Patrn: NO
  1133.       Uses Write Mode: NO
  1134.       Uses Font Sizes: NO
  1135.  
  1136.      This command draws a circular arc, or a segment of a circle.  Drawing
  1137.      begins at <start_ang> and terminates at <end_ang>.  The angles are
  1138.      represented starting at zero for the 3 o'clock position and
  1139.      increasing counterclockwise through a full circle to 360:
  1140.  
  1141.                                90
  1142.                                 |
  1143.                           180---|--- 0
  1144.                                 |
  1145.                                270
  1146.  
  1147.      The arc drawing begins at the <start_angle> and continues counter-
  1148.      clockwise to the <end_angle>.  A full circle will be displayed if
  1149.      <start_ang>=0 and <end_ang>=360.  This command recognizes aspect
  1150.      ratios like the circle command does.  It does not take advantage of
  1151.      line patterns but does comply with line thickness.
  1152.  
  1153.      If both angles are equal, nothing is drawn.
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.      ---------------------------------------------------------------------
  1160.      Draw an Elliptical Arc
  1161.      ---------------------------------------------------------------------
  1162.                Symbol: RIP_OVAL_ARC
  1163.                 Level: 0
  1164.               Command: V
  1165.             Arguments: x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
  1166.                Format: !|A <x> <y> <st_ang> <e_ang> <radx> <rady>
  1167.               Example: !|A1E18003G151Q
  1168.       Uses Draw Color: YES
  1169.       Uses Line Patrn: NO
  1170.       Uses Line Thick: YES
  1171.       Uses Fill Color: NO
  1172.       Uses Fill Patrn: NO
  1173.       Uses Write Mode: NO
  1174.       Uses Font Sizes: NO
  1175.  
  1176.      This command draws an elliptical arc, or a segment of an ellipse.
  1177.      Drawing begins at <st_ang> and terminates at <e_ang>.  The angles are
  1178.      represented starting at zero for 3 o'clock position and increasing
  1179.      counterclockwise through a full ellipse at 360 degrees:
  1180.  
  1181.                                90
  1182.                                 |
  1183.                           180---|--- 0
  1184.                                 |
  1185.                                270
  1186.  
  1187.      The arc drawing begins at the <st_ang> and continues counterclockwise
  1188.      to the <e_ang>.  A complete ellipsewill be displayed if <st_ang>=0
  1189.      and <e_ang>=360.  This command does not utilize "aspect ratios"
  1190.      because of the nature of an Ellipse.  It does not take advantage of
  1191.      line patterns but does comply with line thickness.
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.      ---------------------------------------------------------------------
  1198.      Draw a circular Pie Slice
  1199.      ---------------------------------------------------------------------
  1200.                Symbol: RIP_PIE_SLICE
  1201.                 Level: 0
  1202.               Command: I
  1203.             Arguments: x:2, y:2, start_ang:2, end_ang:2, radius:2
  1204.                Format: !|A <x> <y> <start_ang> <end_ang> <radius>
  1205.               Example: !|A1E18003G15
  1206.       Uses Draw Color: YES
  1207.       Uses Line Patrn: NO
  1208.       Uses Line Thick: YES
  1209.       Uses Fill Color: YES
  1210.       Uses Fill Patrn: YES
  1211.       Uses Write Mode: NO
  1212.       Uses Font Sizes: NO
  1213.  
  1214.      This command draws a "pie slice".  The slice is circular.  It obeys
  1215.      all of the same commands as the Arc command described above.  The
  1216.      ends of the arc are connected to the Center-Point of the Arc with two
  1217.      straight lines.  These two lines converge at the Center-Point.  The
  1218.      interior of the Slice is filled with the current Fill Color and
  1219.      Pattern.  The exterior (outline) of the Slice is drawn using the
  1220.      current drawing color and line thickness.  The Line Pattern feature
  1221.      does not apply to this command.
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.      ---------------------------------------------------------------------
  1228.      Draw an Elliptical Pie Slice
  1229.      ---------------------------------------------------------------------
  1230.                Symbol: RIP_OVAL_PIE_SLICE
  1231.                 Level: 0
  1232.               Command: i
  1233.             Arguments: x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
  1234.                Format: !|A <x> <y> <st_ang> <e_ang> <radx> <rady>
  1235.               Example: !|A1E18003G151Q
  1236.       Uses Draw Color: YES
  1237.       Uses Line Patrn: NO
  1238.       Uses Line Thick: YES
  1239.       Uses Fill Color: YES
  1240.       Uses Fill Patrn: YES
  1241.       Uses Write Mode: NO
  1242.       Uses Font Sizes: NO
  1243.  
  1244.      This command draws an  "elliptical pie slice".  It obeys all of the
  1245.      same commands as the Elliptical Arc command described above.  The
  1246.      ends of the arc are connected to the Center-Point of the Arc with two
  1247.      straight lines.  These two lines converge at the Center-Point.  The
  1248.      interior of the Slice is filled with the current Fill Color and
  1249.      Pattern.  The exterior (outline) of the Slice is drawn using the
  1250.      current drawing color and line thickness.  The Line Pattern feature
  1251.      does not apply to this command.
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.      ---------------------------------------------------------------------
  1258.      Draw a custom "Bezier" curve
  1259.      ---------------------------------------------------------------------
  1260.                Symbol: RIP_BEZIER
  1261.                 Level: 0
  1262.               Command: Z
  1263.             Arguments: x1:2 y1:2  x2:2 y2:2  x3:2 y3:2  x4:2 y4:2  cnt:2
  1264.                Format: !|Z <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4> <cnt>
  1265.               Example: !|Z0A0B0C0D0E0F0G0H1G
  1266.       Uses Draw Color: YES
  1267.       Uses Line Patrn: YES
  1268.       Uses Line Thick: YES
  1269.       Uses Fill Color: NO
  1270.       Uses Fill Patrn: NO
  1271.       Uses Write Mode: YES
  1272.       Uses Font Sizes: NO
  1273.  
  1274.      This command provides customizable Curves.  Four "control points" are
  1275.      used to create the shape of the curve.  The curves beginning point is
  1276.      at point (x1,y1) and it ends at (x4,y4).  Points (x2,y2) and (x3,y3)
  1277.      are not necessarily "on" the curve, but are used to "pull" the curve
  1278.      in their direction.  The diagram below indicates how points 2 and 3
  1279.      can be utilized to form the desired curve.  Note that points 2 and 3
  1280.      are not actually "on" the curve, but points 1 and 4 are.
  1281.  
  1282.                           X2
  1283.  
  1284.                          *****
  1285.                        **     ****
  1286.                       *           **            X4
  1287.                      *              **          *
  1288.                    X1                 *       **
  1289.                                        *    **
  1290.                                         ****
  1291.  
  1292.                                          X3
  1293.  
  1294.      NOTE: That points 2 and 3 are not actually "on" the curve, but points
  1295.            1 and 4 are.
  1296.  
  1297.      The last parameter of this command is the <cnt> parameter.  This
  1298.      determines how many "segments" the curve should be drawn in.  Each
  1299.      segment is in fact, a straight line.  The more segments you allow,
  1300.      the smoother the curve may be.  If a curve does not have a
  1301.      significant amount of "curviness" then a low "count" can improve
  1302.      performance of the curve drawing.  Bezier Curves use "floating point"
  1303.      math internally for its processing.  All paramters specified for this
  1304.      command are simple integers however.
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.      ---------------------------------------------------------------------
  1311.      Draws a polygon using the current color and line style/thickness
  1312.      ---------------------------------------------------------------------
  1313.                Symbol: RIP_POLYGON
  1314.                 Level: 0
  1315.               Command: P
  1316.             Arguments: npoints:2, x1:2, y1:2, ... xn:2, yn:2
  1317.                Format: !|P <npoints> <x1> <y1> ... <xn> <yn>
  1318.               Example: !|P03010105090905
  1319.       Uses Draw Color: YES
  1320.       Uses Line Patrn: YES
  1321.       Uses Line Thick: YES
  1322.       Uses Fill Color: NO
  1323.       Uses Fill Patrn: NO
  1324.       Uses Write Mode: YES
  1325.       Uses Font Sizes: NO
  1326.  
  1327.      This command will draw a multi-sided closed polygon.  The polygon is
  1328.      drawn using the current drawing color, line pattern and thickness.
  1329.      The <npoints> parameter is between 2 and 512 and indicates how many
  1330.      (x,y) coordinate pairs will follow, which is also the number of sides
  1331.      of the polygon.  The polygon interior is not filled by RIP_POLYGON.
  1332.  
  1333.      The polygon is enclosed by the last vertex between xn,yn and x1,y1.
  1334.      In other words, you do not have to connect the end to the beginning -
  1335.      it is automatically done for you.
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.      ---------------------------------------------------------------------
  1342.      Draws a filled polygon, using drawing color, current fill settings
  1343.      ---------------------------------------------------------------------
  1344.                Symbol: RIP_FILL_POLY
  1345.                 Level: 0
  1346.               Command: p
  1347.             Arguments: npoints:2, x1:2, y1:2, ... xn:2, yn:2
  1348.                Format: !|p <npoints> <x1> <y1> ... <xn> <yn>
  1349.               Example: !|p03010105050909
  1350.       Uses Draw Color: YES
  1351.       Uses Line Patrn: YES
  1352.       Uses Line Thick: YES
  1353.       Uses Fill Color: YES
  1354.       Uses Fill Patrn: YES
  1355.       Uses Write Mode: YES
  1356.       Uses Font Sizes: NO
  1357.  
  1358.      This command is identical to RIP_POLYGON, except that the interior of
  1359.      the polygon is filled with the current fill color and fill pattern.
  1360.      The actual outline of the polygon is drawn using the current drawing
  1361.      color, line pattern and thickness.
  1362.  
  1363.      NOTE:  You will get unusual effects if the lines of the polygon
  1364.      overlap, creating a polygon with internal "gaps".  (The rule is
  1365.      this:  regions that are "inside" the polygon an even number of times
  1366.      due to overlap are NOT filled.)  The interior fill does not utilize
  1367.      Write Mode, but the outline of the polygon does.
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.      ---------------------------------------------------------------------
  1374.      Flood Fills a given area of the screen with the current fill settings
  1375.      ---------------------------------------------------------------------
  1376.                Symbol: RIP_FILL
  1377.                 Level: 0
  1378.               Command: F
  1379.             Arguments: x:2, y:2, border:2
  1380.                Format: !|F <x> <y> <border>
  1381.               Example: !|F25090F
  1382.       Uses Draw Color: NO
  1383.       Uses Line Patrn: NO
  1384.       Uses Line Thick: NO
  1385.       Uses Fill Color: YES
  1386.       Uses Fill Patrn: YES
  1387.       Uses Write Mode: NO
  1388.       Uses Font Sizes: NO
  1389.  
  1390.      This command performs a "flood fill" emanating from the given <x,y>
  1391.      point.  The fill "oozes" in all directions up to <border> color, but
  1392.      the border itself is not changed.  Whatever is inside the border
  1393.      that's not the border color gets changed to the current fill color
  1394.      and fill pattern.  If the border color does not completely enclose
  1395.      the <x,y> point, the fill will continue to the edges of the viewport.
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.      ---------------------------------------------------------------------
  1402.      Defines a line style and thickness
  1403.      ---------------------------------------------------------------------
  1404.                Symbol: RIP_LINE_STYLE
  1405.                 Level: 0
  1406.               Command: =
  1407.             Arguments: style:2, user_pat:4, thick:2
  1408.                Format: !|= <style> <user_pat> <thick>
  1409.               Example: !|=01000001
  1410.       Uses Draw Color: NO
  1411.       Uses Line Patrn: YES
  1412.       Uses Line Thick: YES
  1413.       Uses Fill Color: NO
  1414.       Uses Fill Patrn: NO
  1415.       Uses Write Mode: NO
  1416.       Uses Font Sizes: NO
  1417.  
  1418.      This command establishes the current line pattern and thickness for
  1419.      many subsequent graphics primitive commands.  There are four built-in
  1420.      line styles plus provisions for custom line patterns.
  1421.  
  1422.  
  1423.           STYLE
  1424.           =================================================
  1425.             00 ... Normal, Solid Line
  1426.             01 ... Dotted Line
  1427.             02 ... Centered Line
  1428.             03 ... Dashed Line
  1429.             04 ... Custom Defined line (see about <user_pat> below)
  1430.  
  1431.           THICK (these are the only available settings)
  1432.           =================================================
  1433.             01 ... Lines are 1 pixel wide
  1434.             03 ... Lines are 3 pixels wide
  1435.  
  1436.      If the <style> is set to a value of 4 (custom pattern), then the
  1437.      <user_pat> parameter is used as a 16-bit representation of the pixels
  1438.      in the line pattern.  For example:
  1439.  
  1440.  
  1441.               repeating                                            Mega-
  1442.            <---pattern---->   Binary coding       Hex    Decimal   num
  1443.  
  1444.            - - - - - - - -    1010101010101010    AAAA   43690     0XPM
  1445.  
  1446.            ----    ----       1111000011110000    F0F0   61680     1BLC
  1447.  
  1448.  
  1449.      So, the most-significant-bit of <user_pat> is toward the starting
  1450.      point of the line or border that uses this fill pattern.  If the
  1451.      <style> parameter is not 4, then the <user_pat> parameter is ignored.
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.      ---------------------------------------------------------------------
  1458.      Sets the current fill style (predefined patterns), and fill color
  1459.      ---------------------------------------------------------------------
  1460.                Symbol: RIP_FILL_STYLE
  1461.                 Level: 0
  1462.               Command: S
  1463.             Arguments: pattern:2, color:2
  1464.                Format: !|S <pattern> <color>
  1465.               Example: !|S050F
  1466.       Uses Draw Color: NO
  1467.       Uses Line Patrn: NO
  1468.       Uses Line Thick: NO
  1469.       Uses Fill Color: YES
  1470.       Uses Fill Patrn: YES
  1471.       Uses Write Mode: NO
  1472.       Uses Font Sizes: NO
  1473.  
  1474.      This command defines the current fill pattern and fill color for use
  1475.      in subsequent graphics fill operations.  There are twelve (12)
  1476.      predefined fill patterns.  They are:
  1477.  
  1478.           PATTERN DESCRIPTION
  1479.           ==============================================================
  1480.             00    Fill with background color (color #0)
  1481.             01    Solid Fill (fill color)
  1482.             02    Line Fill ................. ----------- (thick lines)
  1483.             03    Light Slash Fill .......... /  /  /  /  (thin lines)
  1484.             04    Normal Slash Fill ......... // // // // (thick lines)
  1485.             05    Normal Backslash Fill ..... \\ \\ \\ \\ (thick lines)
  1486.             06    Light Backslash Fill ...... \  \  \  \  (thin lines)
  1487.             07    Light Hatch Fill .......... ########### (thin lines)
  1488.             08    Heavy Cross Hatch Fill .... XXXXXXXXXXX (thin lines)
  1489.             09    Interleaving Line Fill .... +-+-+-+-+-+ (thin lines)
  1490.             0A    Widely spaced dot fill .... . : . : . : (pixels only)
  1491.             0B    Closely spaced dot fill ... ::::::::::: (pixels only)
  1492.  
  1493.      The <color> parameter is the fill color for subsequent fill commands.
  1494.      The "active" pixels of the pattern become this color.  The "inactive"
  1495.      pixels become the current background color (color 00, typically
  1496.      black).  Fill pattern 00 will set the entire fill area to the
  1497.      background color.  (In this special case, the fill color doesn't
  1498.      matter.)
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.      ---------------------------------------------------------------------
  1505.      Sets a user-definable fill pattern (custom) and fill color
  1506.      ---------------------------------------------------------------------
  1507.                Symbol: RIP_FILL_PATTERN
  1508.                 Level: 0
  1509.               Command: s
  1510.             Arguments: c1:2 c2:2 c3:2 c4:2 c5:2 c6:2 c7:2 c8:2 color:2
  1511.                Format: !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <color>
  1512.               Example: !|s11223344556677880F
  1513.       Uses Draw Color: NO
  1514.       Uses Line Patrn: NO
  1515.       Uses Line Thick: NO
  1516.       Uses Fill Color: YES
  1517.       Uses Fill Patrn: YES
  1518.       Uses Write Mode: NO
  1519.       Uses Font Sizes: NO
  1520.  
  1521.      This command allows you to specify a user-defined, custom Fill
  1522.      Pattern.  This pattern supersedes the predefined patterns of
  1523.      RIP_FILL_STYLE.  A custom fill pattern is an 8x8 pixel array defining
  1524.      which pixels should be drawn in the current fill color (as set by the
  1525.      <color> parameter here).  The other pixels in the fill area are set
  1526.      to the current background color (color 00, typically black).
  1527.  
  1528.      Each of the eight parameters of this command, <c1> through <c8>
  1529.      represent bit-patterns for a line of the 8x8 pixel array.  Each line
  1530.      is comprised of 8 pixels.  The value of each parameter is the binary
  1531.      representation of these 8 pixels as follows:
  1532.  
  1533.           bit   7   6   5   4   3   2   1   0
  1534.               +-------------------------------+
  1535.           c1  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1536.               +-------------------------------+
  1537.           c2  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1538.               +-------------------------------+
  1539.           c3  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1540.               +-------------------------------+
  1541.           c4  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1542.               +-------------------------------+
  1543.           c5  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1544.               +-------------------------------+
  1545.           c6  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1546.               +-------------------------------+
  1547.           c7  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1548.               +-------------------------------+
  1549.           c8  |128| 64| 32| 16| 8 | 4 | 2 | 1 |
  1550.               +-------------------------------+
  1551.  
  1552.      So, c1 is the top, and the most-significant bit is to the left.
  1553.  
  1554.      NOTE: The RIP_FILL_STYLE (predefined fill patterns) and this
  1555.      RIP_FILL_PATTERN (custom fill patterns) completely override one
  1556.      another's effects.
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.      ---------------------------------------------------------------------
  1563.      Defines a rectangular "hot" Mouse Region on screen
  1564.      ---------------------------------------------------------------------
  1565.                Symbol: RIP_MOUSE
  1566.                 Level: 1
  1567.               Command: M
  1568.             Arguments: num:2  x0:2 y0:2  x1:2 y1:2  clk:1 clr:1 res:5 text
  1569.                Format: !|1M <num> <x0><y0> <x1><y1> <clk><clr><res> <text>
  1570.               Example: !|1M00001122331100000host command^M
  1571.       Uses Draw Color: NO
  1572.       Uses Line Patrn: NO
  1573.       Uses Line Thick: NO
  1574.       Uses Fill Color: NO
  1575.       Uses Fill Patrn: NO
  1576.       Uses Write Mode: NO
  1577.       Uses Font Sizes: NO
  1578.  
  1579.      This command ties together three things:
  1580.  
  1581.           A region on the screen
  1582.           A mouse-click event
  1583.           A string of text to be transmitted by the terminal.
  1584.  
  1585.      This command defines a rectangular region on the screen that functions
  1586.      as a "hot" mouse area.  If the user clicks the [left] mouse button
  1587.      while pointing inside the region, then the terminal must transmit the
  1588.      <text> string to the Host.  The (x0,y0) parameter MUST be the
  1589.      upper-left corner, and (x1,y1) MUST be the lower-right corner of the
  1590.      region.
  1591.  
  1592.      The <clk> parameter, if 1, indicates that the region should be
  1593.      visibly inverted while the mouse button is down.  This offers visual
  1594.      feedback.  If <clk> is 0, the region will not be inverted while
  1595.      clicked.
  1596.  
  1597.      The <clr> parameter, if 1, will physically zoom the text window to
  1598.      full screen size and clear the screen.  This is useful if the <text>
  1599.      parameter instructs the host to enter an area of the System that
  1600.      doesn't support RIPscrip graphics.
  1601.  
  1602.      The <text> parameter is a Host command that gets sent when the field
  1603.      is clicked.  You may use a caret (^) to represent control characters,
  1604.      (eg, ^M for carriage return, ^G, ^C, etc).
  1605.  
  1606.      NOTE: You are limited to a maximum of 128 Mouse Regions.  In addition,
  1607.            the 5-byte <res> parameter is RESERVED FOR FUTURE USE, and
  1608.            should be set to zeros (00000).
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.      ---------------------------------------------------------------------
  1615.      Destroys all previously defined "hot" Mouse Regions
  1616.      ---------------------------------------------------------------------
  1617.                Symbol: RIP_KILL_MOUSE_FIELDS
  1618.                 Level: 1
  1619.               Command: K
  1620.             Arguments: <none>
  1621.                Format: !|1K
  1622.               Example: !|1K
  1623.       Uses Draw Color: NO
  1624.       Uses Line Patrn: NO
  1625.       Uses Line Thick: NO
  1626.       Uses Fill Color: NO
  1627.       Uses Fill Patrn: NO
  1628.       Uses Write Mode: NO
  1629.       Uses Font Sizes: NO
  1630.  
  1631.      This command will "forget" all Mouse Regions.  Use it at the beginning
  1632.      of each Scene, so that one scene's Mouse Regions don't get used in
  1633.      another.
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.      ---------------------------------------------------------------------
  1640.      Define a rectangular Text Region
  1641.      ---------------------------------------------------------------------
  1642.                Symbol: RIP_BEGIN_TEXT
  1643.                 Level: 1
  1644.               Command: T
  1645.             Arguments: x1:2, y1:2, x2:2, y2:2, res:2
  1646.                Format: !|1T <x1> <y1> <x2> <y2> <res>
  1647.               Example: !|1T00110011
  1648.       Uses Draw Color: NO
  1649.       Uses Line Patrn: NO
  1650.       Uses Line Thick: NO
  1651.       Uses Fill Color: NO
  1652.       Uses Fill Patrn: NO
  1653.       Uses Write Mode: NO
  1654.       Uses Font Sizes: NO
  1655.  
  1656.      This command defines a rectangular portion of the graphics viewport
  1657.      that is to display text, usually a long stream of text.  Following
  1658.      this command should be a number of RIP_REGION_TEXT commands with the
  1659.      text to be displayed.  The RIP_END_TEXT terminates this stream of
  1660.      text, something like this:
  1661.  
  1662.           RIP_BEGIN_TEXT
  1663.              RIP_REGION_TEXT
  1664.              RIP_REGION_TEXT
  1665.              RIP_REGION_TEXT
  1666.              :
  1667.              RIP_REGION_TEXT
  1668.           RIP_END_TEXT
  1669.  
  1670.      There must be at least one RIP_REGION_TEXT command in between the
  1671.      header and the footer.  There may be as many as needed.
  1672.  
  1673.      These commands ignore the current font "direction"; all text is
  1674.      always displayed horizontally.
  1675.  
  1676.      NOTE:  The "res" parameter is two bytes wide and is RESERVED for
  1677.             future use.
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.      ---------------------------------------------------------------------
  1684.      Display a line of text in the rectangular Text Region
  1685.      ---------------------------------------------------------------------
  1686.                Symbol: RIP_REGION_TEXT
  1687.                 Level: 1
  1688.               Command: t
  1689.             Arguments: justify:1 and text-string
  1690.                Format: !|1t <justify> <text-string>
  1691.               Example: !|1t1This is a text line to be justified
  1692.       Uses Draw Color: YES
  1693.       Uses Line Patrn: NO
  1694.       Uses Line Thick: NO
  1695.       Uses Fill Color: NO
  1696.       Uses Fill Patrn: NO
  1697.       Uses Write Mode: YES
  1698.       Uses Font Sizes: YES
  1699.  
  1700.      A number of these commands may come sandwiched between the
  1701.      RIP_BEGIN_TEXT and RIP_END_TEXT commands.  The <text-string> is
  1702.      already word-wrapped in such a way that it will fit inside the
  1703.      rectangular region based on the current font, font size, and drawing
  1704.      color.
  1705.  
  1706.      There are two possible settings for the <justify> parameter:
  1707.  
  1708.           0 ... Don't right/left justify.  Left-justify only
  1709.  
  1710.           1 ... Perform right/left margin justification of this line
  1711.                 of text except for the last line of a paragraph and
  1712.                 sets of indented lines.
  1713.  
  1714.      If a text line falls off the bottom of the region, it is discarded --
  1715.      the rectangular Text Region does not scroll.
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.      ---------------------------------------------------------------------
  1722.      End a rectangular Text Region
  1723.      ---------------------------------------------------------------------
  1724.                Symbol: RIP_END_TEXT
  1725.                 Level: 1
  1726.               Command: E
  1727.             Arguments: <none>
  1728.                Format: !|1E
  1729.               Example: !|1E
  1730.       Uses Draw Color: NO
  1731.       Uses Line Patrn: NO
  1732.       Uses Line Thick: NO
  1733.       Uses Fill Color: NO
  1734.       Uses Fill Patrn: NO
  1735.       Uses Write Mode: NO
  1736.       Uses Font Sizes: NO
  1737.  
  1738.      This command indicates the end of a formatted text block.  Only one
  1739.      of these "end" commands is necessary for each block.
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.      ---------------------------------------------------------------------
  1746.      Copies a rectangular screen image onto the Clipboard (as an Icon)
  1747.      ---------------------------------------------------------------------
  1748.                Symbol: RIP_GET_IMAGE
  1749.                 Level: 1
  1750.               Command: C
  1751.             Arguments: x0:2, y0:2, x1:2, y1:2, res:1
  1752.                Format: !|1C <x0> <y0> <x1> <y1> <res>
  1753.               Example: !|1C001122330
  1754.       Uses Draw Color: NO
  1755.       Uses Line Patrn: NO
  1756.       Uses Line Thick: NO
  1757.       Uses Fill Color: NO
  1758.       Uses Fill Patrn: NO
  1759.       Uses Write Mode: NO
  1760.       Uses Font Sizes: NO
  1761.  
  1762.      This command instructs the terminal program to copy the rectangular
  1763.      region defined by (x0,y0) to (x1,y1) onto an internal Clipboard for
  1764.      future use.  This combined with the Paste Clipboard command can
  1765.      provide an extremely powerful and efficient mechanism to avoid
  1766.      baud-rate bandwidth limitations.  The (x0,y0) parameter MUST specify
  1767.      the upper-left corner of the region and the (x1,y1) parameter MUST
  1768.      specify the lower-right corner.  If the indicated coordinates are in
  1769.      anyway invalid, the command is ignored.  The Clipboard is completely
  1770.      overwritten by this command (the previous contents are lost).
  1771.  
  1772.      NOTE: The <res> parameter is RESERVED FOR FUTURE USE and should be
  1773.            set to zero.
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.      ---------------------------------------------------------------------
  1780.      Pastes the clipboard (Icon) contents onto the screen
  1781.      ---------------------------------------------------------------------
  1782.                Symbol: RIP_PUT_IMAGE
  1783.                 Level: 1
  1784.               Command: P
  1785.             Arguments: x:2, y:2, mode:2, res:1
  1786.                Format: !|1P <x> <y> <mode> <res>
  1787.               Example: !|1P0011010
  1788.       Uses Draw Color: NO
  1789.       Uses Line Patrn: NO
  1790.       Uses Line Thick: NO
  1791.       Uses Fill Color: NO
  1792.       Uses Fill Patrn: NO
  1793.       Uses Write Mode: NO
  1794.       Uses Font Sizes: NO
  1795.  
  1796.      This command takes the contents of the Clipboard (if any) and pastes
  1797.      the image onto the screen starting at the upper-left corner of the
  1798.      image of (x,y).  If the right edge of the image would go off-screen,
  1799.      the paste command is ignored.  The Height and Width of the clipboard
  1800.      image is recorded on the Clipboard, so this command doesn't need to
  1801.      supply it.
  1802.  
  1803.      The <mode> parameter defines "how" the image will be pasted on the
  1804.      screen:
  1805.  
  1806.          MODE DESCRIPTION
  1807.          ==============================================================
  1808.            00 Paste the image on-screen normally                 (COPY)
  1809.            01 Exclusive-OR  image with the one already on screen (XOR)
  1810.            02 Logically OR  image with the one already on screen (OR)
  1811.            03 Logically AND image with the one already on screen (AND)
  1812.            04 Paste the inverse of the image on the screen       (NOT)
  1813.  
  1814.      NOTE: The 1-byte <res> parameter is RESERVED FOR FUTURE USE and
  1815.            should be set to zero.
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.      ---------------------------------------------------------------------
  1822.      Writes the contents of the Clipboard (Icon) to disk
  1823.      ---------------------------------------------------------------------
  1824.                Symbol: RIP_WRITE_ICON
  1825.                 Level: 1
  1826.               Command: W
  1827.             Arguments: res:1, filename
  1828.                Format: !|1W <res> <filename>
  1829.               Example: !|1W0filename.icn
  1830.       Uses Draw Color: NO
  1831.       Uses Line Patrn: NO
  1832.       Uses Line Thick: NO
  1833.       Uses Fill Color: NO
  1834.       Uses Fill Patrn: NO
  1835.       Uses Write Mode: NO
  1836.       Uses Font Sizes: NO
  1837.  
  1838.      This command takes the contents of the Clipboard and writes it to a
  1839.      disk file.  This Icon file can be loaded later with a RIP_LOAD_ICON
  1840.      command and stamped on the screen.
  1841.  
  1842.      The command instructs the terminal to store an Icon on the terminal's
  1843.      disk drive, or on some appropriate storage media.  Path or
  1844.      subdirectory information is not allowed in the filename portion of
  1845.      the command.  If the clipboard is nonexistent (ie, at the beginning
  1846.      of a scene), this command is ignored.  If an Icon by the same name
  1847.      already exists on disk, it is overwritten.
  1848.  
  1849.      NOTE: The <res> parameter is RESERVED FOR FUTURE USE and should be
  1850.            set to zero.
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.      ---------------------------------------------------------------------
  1857.      Loads and displays a disk-based Icon to the screen
  1858.      ---------------------------------------------------------------------
  1859.                Symbol: RIP_LOAD_ICON
  1860.                 Level: 1
  1861.               Command: I
  1862.             Arguments: x:2, y:2, mode:2, clipboard:1, res:2, filename
  1863.                Format: !|1I <x> <y> <mode> <clipboard> <res> <filename>
  1864.               Example: !|1I001101010button.icn
  1865.       Uses Draw Color: NO
  1866.       Uses Line Patrn: NO
  1867.       Uses Line Thick: NO
  1868.       Uses Fill Color: NO
  1869.       Uses Fill Patrn: NO
  1870.       Uses Write Mode: NO
  1871.       Uses Font Sizes: NO
  1872.  
  1873.      This command instructs the terminal to read an Icon from disk and
  1874.      display it at the given upper-left (x,y) location.  If the width or
  1875.      height of the Icon would make it go off the right or left edge of the
  1876.      screen, the Icon will not be displayed.  The <mode> parameter defines
  1877.      the modes in which the Icon will be displayed on the screen.  The
  1878.      modes are identical to the RIP_PUT_IMAGE command, and are as follows:
  1879.  
  1880.      The .ICN file extension does not need to be included as part of the
  1881.      filename.  If omitted, it will automatically be appended to the
  1882.      filename.  If an extension is provided, it will be used verbatim.
  1883.  
  1884.          Mode Description
  1885.          ==============================================================
  1886.            00 Paste the image on-screen normally                 (COPY)
  1887.            01 Exclusive-OR  image with the one already on screen (XOR)
  1888.            02 Logically OR  image with the one already on screen (OR)
  1889.            03 Logically AND image with the one already on screen (AND)
  1890.            04 Paste the inverse of the image on the screen       (NOT)
  1891.  
  1892.      If the <clipboard> parameter is 1, then not only is the image pasted
  1893.      on screen, but it is also copied into the Clipboard.  If 0, it's
  1894.      simply pasted on the screen.
  1895.  
  1896.      The <filename> parameter must not contain any subdirectory or path
  1897.      information and must specify a valid Icon file name.  If the Icon
  1898.      cannot be located or an error occurs on the disk, then a box should
  1899.      be displayed on screen indicating that the given Icon File could not
  1900.      be loaded.  This visual prompt indicates that something is amiss to
  1901.      the end-user.
  1902.  
  1903.      NOTE: The 2-byte <res> parameter is RESERVED FOR THE FUTURE and
  1904.            unlike many other previously mentioned reserved parameters,
  1905.            should be set to "10".
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.      ---------------------------------------------------------------------
  1912.      Button Style Definition
  1913.      ---------------------------------------------------------------------
  1914.                Symbol: RIP_BUTTON_STYLE
  1915.                 Level: 1
  1916.               Command: B
  1917.             Arguments: wid:2 hgt:2 orient:2 flags:4 size:2 dfore:2 
  1918.                        dback:2 bright:2 dark:2 surface:2 grp_no:2 flags2:2
  1919.                        uline_col:2 corner_col:2 res:6
  1920.                Format: !|1B <wid> <hgt> <orient> <flags> <bevsize> <dfore>
  1921.                        <dback> <bright> <dark> <surface> <grp_no> <flags2>
  1922.                        <uline_col> <corner_col> <res>
  1923.               Example: !|1B0000010274030E000F08070000000204000000
  1924.       Uses Draw Color: NO
  1925.       Uses Line Patrn: NO
  1926.       Uses Line Thick: NO
  1927.       Uses Fill Color: NO
  1928.       Uses Fill Patrn: NO
  1929.       Uses Write Mode: NO
  1930.       Uses Font Sizes: NO
  1931.  
  1932.      This RIPscrip command is probably one of the most complex in the
  1933.      entire protocol.  It defines how subsequent RIP_BUTTON commands will
  1934.      be interpretted.  The purpose of this command is to define what a 
  1935.      Button is and how they operate.  Buttons can have many different
  1936.      configurations, flags, and styles.  With the diversity of modes that
  1937.      the Button can take on, complexity is a necessary evil.
  1938.  
  1939.      This command does not actually do anything visibly on the screen. 
  1940.      Simply put, this creates an internal definition for the Button mode
  1941.      which will be used with RIP_BUTTON commands after the definition is 
  1942.      created.
  1943.  
  1944.      Every Button can have an optional text label.  It can appear in
  1945.      several different locations compared to the Button itself.  This is
  1946.      specified in the <orient> parameter.  The actual text of the label is
  1947.      not specified with this command, it is specified when you actually
  1948.      create a Button (see RIP_BUTTON below).  The value that <orient> can
  1949.      be is as follows:
  1950.  
  1951.           Value     Description of Orientation
  1952.           ===================================================
  1953.           00        Display Label above of Button
  1954.           01        Display Label to the Left of Button
  1955.           02        Display Label in the center of the Button
  1956.           03        Display Label to the Right of Button
  1957.           04        Display Label beneath the Button
  1958.  
  1959.  
  1960.      The <hgt> and <wid> parameters represent the fixed height and width of
  1961.      the Button (applies only to Plain Buttons).  If both values are
  1962.      greater than zero, then this will represent the actual size of the
  1963.      Button (its dimensions are not specified by the RIP_BUTTON command). 
  1964.      If both of these are set to zero, then the actual RIP_BUTTON command
  1965.      will specify the size of the particular Button (dynamic sizing).
  1966.  
  1967.      The <bevsize> parameter is only used if the Bevel flag is specified. 
  1968.      When active, this parameter will determine how many pixels thick the
  1969.      bevel should be.  This may be any value greater or equal to zero.
  1970.  
  1971.      There are a large number of flag values that can be combined to
  1972.      achieve a great many effects.  There are two flag parameters for the
  1973.      RIP_BUTTON_STYLE command, <flags> and <flags2>.  They are detailed in
  1974.      the two tables that follow in this Section.  You may combine any of
  1975.      the flags in the first table together simply by adding the "Value" of
  1976.      each one together and representing that number as a MegaNum.  See the
  1977.      Section in this manual for a "Table of MegaNums".
  1978.  
  1979.      The <dfore> and <dback> parameters are used with the text label.  The
  1980.      <dfore> parameter is the foreground color for the text.  It is always
  1981.      used to determine the color of the text label.  The <dback> color is
  1982.      the color of the dropshadow (if any).  This parameter is only used
  1983.      when you have specified the "Dropshadow" flag in the <flags>
  1984.      parameter (see below).
  1985.  
  1986.      The <bright>, <dark> and <surface> parameters are used with Plain
  1987.      Buttons and with the Special Effects styles (see <flags> below). 
  1988.      These colors represent the hilighted color, the shadowed color, and
  1989.      the regular surface color that is used in Special Effects.  Typical
  1990.      color combinations for these colors might be White, Dark-Gray and
  1991.      Light-Gray respectively for a "chiseled steel" appearance.  Each of
  1992.      these values can contain a two-digit value representing any valid
  1993.      color code that may be used in the RIP_COLOR command.
  1994.  
  1995.      In addition to the special effects colors, are two additional colors
  1996.      that can be used, <uline_color> which is used for the color of the
  1997.      underline (in the text label), and <corner_color> which is used to 
  1998.      display the colors of corners for things like the Bevel, Recess, etc.
  1999.  
  2000.      The <grp_no> parameter determines which Button Group subsequent
  2001.      RIP_BUTTON commands will be associated with.  Button Groups are used
  2002.      to maintain groups of Buttons for things like Radio Buttons and/or 
  2003.      Checkbox Buttons.  See the section entitled THE BUTTON COMMAND for
  2004.      more information on these modes, and what Button Groups can offer. 
  2005.      This value can range anywhere from 0-Z (i.e., 0-35).  You should not
  2006.      mix Checkbox and Radio buttons in the same group. -- unpredictable
  2007.      things may happen if you do.
  2008.  
  2009.      Some <flags> are mutually exclusive.  For example, you can only have
  2010.      one of the "Plain", "Icon", or "Clipboard" flags chosen at once.  To
  2011.      better assist you in determining which values can be combined with 
  2012.      each other, the right-most five columns in the next two tables explain
  2013.      if the specific flag can be used under a specific condition.  For
  2014.      example, you cannot choose the "Hot Icon" flag if you are dealing with
  2015.      a Clipboard Button.  Another example is that you cannot underline the
  2016.      hotkey character in the label if it is not a Mouse Button.
  2017.  
  2018.      The following table contains the possible flag values for the <flags>
  2019.      parameter.  Each of these values may be combined to achieve a
  2020.      "composite" group of flags.  See the preceding paragraphs for a more
  2021.      detailed explanation of this method.
  2022.  
  2023.      VALUE  DESCRIPTION OF FLAGS FIELD #1    ICON CLIP PLAIN MOUSE NO-MOUSE
  2024.      ======================================================================
  2025.      1      Button is a "Clipboard Button"     N    Y    N     Y      Y
  2026.      2      Button is "invertable"             Y    Y    Y     Y      N
  2027.      4      Reset screen after button click    Y    Y    Y     Y      N
  2028.      8      Display Chisel special effect      Y    Y    Y     Y      Y
  2029.      16     Display Recessed special effect    Y    Y    Y     Y      Y
  2030.      32     Dropshadow the label (if any)      Y    Y    Y     Y      Y
  2031.      64     Auto-stamp image onto Clipboard    Y    Y    Y     Y      Y
  2032.      128    Button is an "Icon Button"         Y    N    N     Y      Y
  2033.      256    Button is a "Plain Button"         N    N    Y     Y      Y
  2034.      512    Display Bevel special effect       Y    Y    Y     Y      Y
  2035.      1024   Button is a Mouse Button           Y    Y    Y     Y      N
  2036.      2048   Underline hot-key in label         Y    Y    Y     Y      N
  2037.      4096   Make Icon Button use Hot Icons     Y    N    N     Y      N
  2038.      8192   Adjust vert. centering of label    Y    Y    Y     Y      Y
  2039.      16384  Button belongs to a Radio Group    Y    Y    Y     Y      N
  2040.      32768  Display Sunken special effect      Y    Y    Y     Y      Y
  2041.  
  2042.  
  2043.  
  2044.  
  2045.      The following table describes the possible flag settings for the
  2046.      <flags2> parameter:
  2047.  
  2048.      VALUE  DESCRIPTION OF FLAGS FIELD #2    ICON CLIP PLAIN MOUSE NO-MOUSE
  2049.      ======================================================================
  2050.      1      Button is in a Checkbox Group      Y    Y    Y     Y      N
  2051.      2      Hilight Hotkey character           Y    Y    Y     Y      N
  2052.      4      Explode (Zoom Out when clicked)    Y    Y    Y     Y      N
  2053.      8      Left Justify Label (top/cent/bot)  Y    Y    Y     Y      Y
  2054.      16     Right Justify Label (" / "  / ")   Y    Y    Y     Y      Y
  2055.  
  2056.  
  2057.  
  2058.  
  2059.      ---------------------------------------------------------------------
  2060.      Define a Mouse Button
  2061.      ---------------------------------------------------------------------
  2062.                Symbol: RIP_BUTTON
  2063.                 Level: 1
  2064.               Command: U
  2065.             Arguments: x0:2 y0:2 x1:2 y1:2 hotkey:2 flags:1 res:1 ...text
  2066.                Format: !|1U <x0> <y0> <x1> <y1> <hotkey> <flags> <res> <text>
  2067.               Example: !|1U010100003200iconfile.icn<>Label<>Host Cmd^m
  2068.       Uses Draw Color: NO
  2069.       Uses Line Patrn: NO
  2070.       Uses Line Thick: NO
  2071.       Uses Fill Color: NO
  2072.       Uses Fill Patrn: NO
  2073.       Uses Write Mode: NO
  2074.       Uses Font Sizes: YES
  2075.  
  2076.      This command physically creates a new Button using the previously
  2077.      described RIP_BUTTON_STYLE command.  You may have at most 128
  2078.      different Mouse Buttons (you may have any number of non-Mouse 
  2079.      Buttons).
  2080.  
  2081.      The <x0> and <y0> parameters for this command designate the upper-left
  2082.      corner of the Button.  This (X,Y) location may not be the actual
  2083.      "absolute" corner position of the Button, as it may be adjusted via
  2084.      the Special Effects functions that are part of the RIP_BUTTON_STYLE
  2085.      command (see above).
  2086.  
  2087.      The <x1> and <y1> parameters are only used for Plain Buttons when you
  2088.      have not specified a specific Height and Width in the
  2089.      RIP_BUTTON_STYLE command.  These parameters are used in Dynamically
  2090.      Sized Buttons.  If the Height and Width in the RIP_BUTTON_STYLE are
  2091.      non-zero, then these two parameters are set to zero.
  2092.  
  2093.      The (x0,y0) and (x1,y1) will be modified by the following values for
  2094.      the different special effects:
  2095.  
  2096.      EFFECT TYPE    X0 ADJ         Y0 ADJ         X1 ADJ         Y1 ADJ
  2097.      =======================================================================
  2098.      Bevel          -bevel size    -bevel size    +bevel size    +bevel size
  2099.      Recess         -2             -2             +2             +2
  2100.      Sunken         0              0              0              0
  2101.      Chisel         0              0              0              0
  2102.  
  2103.  
  2104.      The <hotkey> parameter is only used with Mouse Buttons.  It is the
  2105.      ASCII code for the keystroke that will activate this Button.  It is
  2106.      represented as a two-digit MegaNum.  If this character exists in the
  2107.      text label, and the Underline flag is enabled in the
  2108.      RIP_BUTTON_STYLE, then the character will be underlined in the label.
  2109.  
  2110.      The <flags> parameter can be set to one of two values, 0 or 1.  If it
  2111.      is set to 1, then the Button is already "selected".  By selected, we
  2112.      mean that it is already clicked and should be initially drawn as
  2113.      clicked.  This is typically used for Radio Buttons and/or Check
  2114.      Boxes.  This only affects the image.  The Host Command WILL NOT be
  2115.      automatically sent to the host when a selected Button is drawn.  If
  2116.      this parameter is set to 0, then the Button will be drawn in normal,
  2117.      unselected mode.
  2118.  
  2119.      The <text> parameter for this command is somewhat different than those
  2120.      found in previously described RIPscrip commands.  All other RIPscrip
  2121.      commands only have one text parameter.  This command requires 
  2122.      anywhere from 0-3 text parameters.  The way RIPscrip accomplishes this
  2123.      is by separating each block in the <text> parameter with the
  2124.      delimiter "<>".  This text parameter delimiter is not needed before
  2125.      the first text block, but is necessary between the 1st and 2nd
  2126.      blocks, and the 2nd and 3rd blocks.  Here is an example of a typical
  2127.      text parameter for this command:
  2128.  
  2129.                  ICONFILE.ICN<>TEXT LABEL<>HOST COMMAND
  2130.  
  2131.      The actual syntax of this text parameter is as follows:
  2132.  
  2133.               [icon-file][[<>text-label][<>host-command]]
  2134.  
  2135.      The block described as ICONFILE.ICN is actually the Icon Filename that
  2136.      will be used for the Button if it is an Icon Button.  If it is not an
  2137.      Icon Button, then this block will read "<>" all by itself (a "null"
  2138.      block).
  2139.  
  2140.      The .ICN file extension does not need to be included as part of the
  2141.      filename.  If omitted, it will automatically be appended to the
  2142.      filename.  If an extension is provided, it will be used verbatim.
  2143.  
  2144.      The "TEXT LABEL" block is actually the text that will be used to
  2145.      descriptively label the Button.  You may also specify a "null" block
  2146.      for no label (i.e., "<>").
  2147.  
  2148.      The final block of the <text> parameter is the Host Command.  This
  2149.      block contains any text that should be sent to the Host after this
  2150.      Button is clicked.  This may contain any Control Characters, Pick-List
  2151.      definitions, Text Variables or Template Definitions.  This block
  2152.      might be "segmented" into multiple Host Command segments.  See the
  2153.      section entitled HOST COMMANDS in this Manual for additional
  2154.      information on these Host Command features.
  2155.  
  2156.      Not all of the blocks in the <text> parameter need to be specified. 
  2157.      Here are examples of the valid combinations of text blocks:
  2158.  
  2159.      PARAMETER EXAMPLE        DESCRIPTION OF THE TEXT PARAMETER
  2160.      ===================================================================
  2161.      icon<>label<>host_cmd    Specify all three blocks
  2162.      <>label<>host_cmd        2 blocks specified; no icon
  2163.      icon<>label<>            2 blocks specified; no host cmd
  2164.      icon<>label              2 blocks specified; no host cmd
  2165.      <><>host_cmd             1 block specified; no icon or label
  2166.      <>label<>                1 block specified; no icon or host cmd
  2167.      <>label                  1 bloc specified; no icon or host cmd
  2168.      icon<><>                 1 block specified; no label or host cmd
  2169.      icon<>                   1 block specified; no label or host cmd
  2170.      icon                     1 block specified; no label or host cmd
  2171.      <><><>                   A blank text parameter; all blocks omitted
  2172.      <><>                     A blank text parameter; all blocks omitted
  2173.      <>                       A blank text parameter; all blocks omitted
  2174.  
  2175.  
  2176.      NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  2177.             Communications, Inc..  It should be set to 0 for compatibility
  2178.             with future releases.
  2179.  
  2180.  
  2181.  
  2182.  
  2183.      ---------------------------------------------------------------------
  2184.      Define a Text Variable
  2185.      ---------------------------------------------------------------------
  2186.                Symbol: RIP_DEFINE
  2187.                 Level: 1
  2188.               Command: D
  2189.             Arguments: flags:3 res:2 ...text
  2190.                Format: !|1D <flags> <res> <text>
  2191.               Example: !|1D00700text_var,60:?question?default data
  2192.       Uses Draw Color: NO
  2193.       Uses Line Patrn: NO
  2194.       Uses Line Thick: NO
  2195.       Uses Fill Color: NO
  2196.       Uses Fill Patrn: NO
  2197.       Uses Write Mode: NO
  2198.       Uses Font Sizes: NO
  2199.  
  2200.      This command is used to create a text variable on the Client system
  2201.      (i.e., the Terminal system).  A text variable is more fully covered
  2202.      in the section entitled HOST COMMANDS.  Simply put, a text variable is
  2203.      a piece of information assigned to a 1-12 character identifier that
  2204.      can either be saved to a local database file (static variables), or
  2205.      to memory (dynamic variables).  Variable Identifiers can be 1-12
  2206.      characters in length.  You may use any alphanumeric character and
  2207.      underscores (_) in the identifier.  An underscore cannot be the first
  2208.      character, nor can the first character of an identifier be a number.
  2209.  
  2210.      The <flags> parameter of this command combines three separate values
  2211.      into one MegaNum flag that determines how the variable definition
  2212.      will operate.  Here are the possible flag values:
  2213.  
  2214.                   VALUE     DESCRIPTION OF FLAG
  2215.                   =========================================
  2216.                   001       Save Variable to database
  2217.                   002       Cannot specify a blank response
  2218.                   004       Non-interactive query
  2219.  
  2220.  
  2221.      When a variable is flagged as "Save to Database", it becomes a part of
  2222.      the Client system's actual configuration.  The value is saved
  2223.      indefinitely until either changed, or manually erased.  You may choose
  2224.      not to allow the user to enter a blank response.  This basically
  2225.      requires them to enter some piece of information for the variable.
  2226.  
  2227.      The last flag determines whether the definition is interactive or not.
  2228.      An interactive definition will attempt to define the variable.  If it
  2229.      does exist, it pops the value up on the screen asking the user to
  2230.      confirm if the value is correct.  If it does not exist, a similar
  2231.      pop-up box will appear asking the user to enter some data for the
  2232.      given variable.
  2233.  
  2234.      In a non-interactive situation, the Client system will check to see if
  2235.      the variable exists.  If it does, then nothing happens (unless a
  2236.      default response is specified in this command, whereby the Client's
  2237.      variable is updated with the new information).  If the value is not
  2238.      defined, then this definition becomes interactive by default, since
  2239.      the user actually has to enter something anyway.
  2240.  
  2241.      The <text> parameter for this command is also segmented in nature,
  2242.      much like the RIP_BUTTON command is.  An example of a segmented
  2243.      <text> parameter for the RIP_DEFINE command might be as follows:
  2244.  
  2245.  
  2246.                FULL_NAME,30:?What is your full name?John Doe
  2247.  
  2248.  
  2249.      The actual syntax of the Variable Define text parameter is as follows:
  2250.  
  2251.  
  2252.        variable-identifier[,field-width]:[?question-text?][default-value]
  2253.  
  2254.  
  2255.      There are several different segments in this parameter as you can see.
  2256.      The first section is the variable- identifier.  Immediately after it
  2257.      is an optional field-width.  If the field width is omitted, it will
  2258.      default to a value of  60.  You should limit the values of this width
  2259.      from 1-60.
  2260.  
  2261.      Immediately following the identifier field-width parameter is a colon
  2262.      (:).  The colon indicates that the variable identifier field is
  2263.      completed and that the remainder of the text parameter is to contain
  2264.      the question and/or the default response (if any).  If no question or
  2265.      default response is provided, the text parameter would read 
  2266.      "TEXT_VAR,width:" with no additional data.
  2267.  
  2268.      The question-text is specified by a question mark (?) followed by the
  2269.      actual text of the question, followed by a trailing question mark. 
  2270.      The basic format of the question segment is as follows:
  2271.  
  2272.  
  2273.                              ?this is a question?
  2274.  
  2275.  
  2276.      The remainder of the text parameter consists of a default-value for
  2277.      the variable's contents.  It may be omitted if you wish, to make it
  2278.      so that the user must enter his/her own value instead of some "canned
  2279.      response".
  2280.  
  2281.  
  2282.      NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  2283.             Communications, Inc..  It should be set to 00 for compatibility
  2284.             with future releases.
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.      ---------------------------------------------------------------------
  2291.      Query the contents of a Text Variable
  2292.      ---------------------------------------------------------------------
  2293.                Symbol: RIP_QUERY
  2294.                 Level: 1
  2295.               Command: <escape>
  2296.             Arguments: res:4 ...text
  2297.                Format: !|1<escape> <res> <text>
  2298.               Example: !|1<escape>0000this is a query $COMMAND$^m
  2299.       Uses Draw Color: NO
  2300.       Uses Line Patrn: NO
  2301.       Uses Line Thick: NO
  2302.       Uses Fill Color: NO
  2303.       Uses Fill Patrn: NO
  2304.       Uses Write Mode: NO
  2305.       Uses Font Sizes: NO
  2306.  
  2307.      The Query Text Variable RIPscrip command instructs the Client system
  2308.      to immediately respond with some piece of information, whether
  2309.      statically stored (i.e., in a database), stored internally in RAM
  2310.      (dynamic information), or pre-defined Text Variables.
  2311.  
  2312.      This command is unique in RIPscrip in the fact that the command
  2313.      character that is used is NOT a printable character.  We use the
  2314.      Escape character (ascii 27) to introduce this command as a measure
  2315.      of Security.  Since the Query command can query the terminal for
  2316.      some critical (potentially private) information, you would not
  2317.      want a End-User to be able to Query another User's terminal for
  2318.      something like his Address Information, or something that he
  2319.      wouldn't want to otherwise divulge to unauthorized people.  Since
  2320.      most BBS'es do not allow the User to enter an Escape character,
  2321.      this character is ideal for this purpose.  Using an Escape, allows
  2322.      only the Host under most circumstances to be in control of any
  2323.      Queries.
  2324.  
  2325.      This command is very flexible in that you can specify Control
  2326.      Characters, Pick-List definitions, Text Variable insertion, and even
  2327.      Host Command Template definitions.  See the section of this Manual
  2328.      entitled HOST COMMANDS for a more detailed explanation of Host
  2329.      Commands and these specific features.
  2330.  
  2331.      Basically put, a Query command will be immediately acted upon by the
  2332.      Terminal program when received.  The Query command's <text> parameter
  2333.      can contain any number of Host Command "segments", which can instruct
  2334.      the terminal "how to" send data to the host, and more specifically,
  2335.      what data to send to the host.
  2336.  
  2337.      Some examples of query statements might be any of the following:
  2338.  
  2339.         ^m  ......................... Send a carriage return to the BBS
  2340.                                       right now
  2341.         My name is $FULL_NAME$^m  ... Send the text "My name is 
  2342.                                       <insert-name-here>" followed by a 
  2343.                                       carriage return to the BBS.  The
  2344.                                       <insert-name-here> will be replaced
  2345.                                       with whatever the the variable
  2346.                                       $FULL_NAME$ contains.
  2347.  
  2348.      See the section entitled HOST COMMANDS for a detailed explanation of
  2349.      Host Commands, and what you can do with the Query command.
  2350.  
  2351.      NOTE:  The <res> parameter is reserved for future use by TeleGrafix
  2352.             Communications, Inc..  It should be set to 0000 for
  2353.             compatibility with future releases.
  2354.  
  2355.  
  2356.  
  2357.  
  2358.      ---------------------------------------------------------------------
  2359.      Copy screen region up/down 
  2360.      ---------------------------------------------------------------------
  2361.                Symbol: RIP_COPY_REGION
  2362.                 Level: 1
  2363.               Command: G
  2364.             Arguments: x0:2 y0:2 x1:2 y1:2 res:2 dest_line:2
  2365.                Format: !|1G <x0> <y0> <x1> <y1> <res> <dest_line>
  2366.               Example: !|1G080G140M0005
  2367.       Uses Draw Color: NO
  2368.       Uses Line Patrn: NO
  2369.       Uses Line Thick: NO
  2370.       Uses Fill Color: NO
  2371.       Uses Fill Patrn: NO
  2372.       Uses Write Mode: NO
  2373.       Uses Font Sizes: NO
  2374.  
  2375.      This command physically "copies" a rectangular region of the
  2376.      graphics screen up or down.  The <dest_line> parameter is the Y
  2377.      position that is the destination scan line to receive the region.
  2378.      The Destination of the copy can overlap the original region, but
  2379.      cannot be on the same line.  You cannot move the image area left or
  2380.      right at all.  This command is designated for vertical scrolling of
  2381.      graphical data either up or down.
  2382.  
  2383.      Due to hardware restrictions, the X0 and X1 parameters must be evenly
  2384.      divisible by eight (8) (e.g., 0, 8, 16, etc).  If the X0 and X1
  2385.      parameters are NOT evenly divisible by eight, then the X0 parameter
  2386.      will be reduced to the next most eight-pixel boundary, and the X1
  2387.      parameter will be increased to the next eight-pixel boundary.  For
  2388.      example, if X0=14, and X1=38, then X0 would be adjusted DOWN to 8,
  2389.      and X1 would be adjusted UP to 40.  This is to ensure that the
  2390.      desired graphical region is scrolled.
  2391.  
  2392.      The original image area is left on the screen (is not cleared).  So
  2393.      if you wish to perform some kind of scrolling effect, you will have
  2394.      to clear the original area yourself.  
  2395.  
  2396.      If the destination region would place the image partially off-screen,
  2397.      then the entire command is ignored!
  2398.  
  2399.  
  2400.      NOTE:  The <res> parameter is reserved for future development by
  2401.             TeleGrafix.
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.      ---------------------------------------------------------------------
  2408.      Playback local .RIP scene file
  2409.      ---------------------------------------------------------------------
  2410.                Symbol: RIP_READ_SCENE
  2411.                 Level: 1
  2412.               Command: R
  2413.             Arguments: res:8 filename...
  2414.                Format: !|1R <res> <filename>
  2415.               Example: !|1R00000000testfile.rip
  2416.       Uses Draw Color: YES
  2417.       Uses Line Patrn: YES
  2418.       Uses Line Thick: YES
  2419.       Uses Fill Color: YES
  2420.       Uses Fill Patrn: YES
  2421.       Uses Write Mode: YES
  2422.       Uses Font Sizes: YES
  2423.  
  2424.      This command instructs the remote terminal to playback a local .RIP
  2425.      file.  The current execution of RIPscrip commands will be temporarily
  2426.      suspended and the contents of the designated RIP file will begin
  2427.      executing.  Regardless of whether or not the current RIPscrip code
  2428.      coming across the modem is in the middle of a line or not, the RIP
  2429.      playback file will be assumed to start at the beginning of a line.
  2430.      Therefore, if a RIP_READ_SCENE command is located in a .RIP file,
  2431.      it must be the very last command on the line, followed by a carriage
  2432.      return instead of a command delimiter (|).  This ensures that the
  2433.      loaded .RIP file will begin executing properly with the correct
  2434.      delimiters found in the correct places.
  2435.  
  2436.      The RIP playback file can alter colors, fonts, or whatever.  Once
  2437.      the playback of the file is complete, the remaining RIPscrip code
  2438.      that was temporarily suspended will be resume execution.  Any changes
  2439.      that appeared in the loaded playback file will remain in effect when
  2440.      the resumed code is processed.  In other words, if you change a color
  2441.      or a font in the playback file and leave them changed, they will
  2442.      remain in effect during the resumed execution.
  2443.  
  2444.         NOTE:  The <res> parameter is reserved for future development
  2445.                by TeleGrafix.  It should be set to "00000000" for
  2446.                compatibility with future releases.
  2447.  
  2448.  
  2449.  
  2450.  
  2451.      ---------------------------------------------------------------------
  2452.      Query existing information on a particular file
  2453.      ---------------------------------------------------------------------
  2454.                Symbol: RIP_FILE_QUERY
  2455.                 Level: 1
  2456.               Command: F
  2457.             Arguments: mode:2 res:4 filename...
  2458.                Format: !|1F <mode> <res> <filename>
  2459.               Example: !|1F010000testfile.icn
  2460.       Uses Draw Color: NO
  2461.       Uses Line Patrn: NO
  2462.       Uses Line Thick: NO
  2463.       Uses Fill Color: NO
  2464.       Uses Fill Patrn: NO
  2465.       Uses Write Mode: NO
  2466.       Uses Font Sizes: NO
  2467.  
  2468.      This command queries the existance of a particular file, regardless
  2469.      of file type.  It is intended for use by Host systems to determine
  2470.      if a particular Icon or RIP file exists on the remote terminal's
  2471.      hard disk.
  2472.  
  2473.      There are a variety of ways you can query for filenames.  The <mode>
  2474.      parameter determines the method that this command will respond to
  2475.      the Host.  Note that this command instructs the terminal to send
  2476.      a response to the Host immediately upon execution of this command.
  2477.  
  2478.      The following table is a listing of the possible values for <mode>:
  2479.  
  2480.           VALUE     DESCRIPTION
  2481.           ==============================================================
  2482.            00       Simply query the existance of the file.  If it
  2483.                     exists, a "1" is returned.  Otherwise a "0" is
  2484.                     returned to the Host (without a carriage return).
  2485.            01       Same as 0 above, except a carriage return is
  2486.                     added after the response.
  2487.            02       Queries the existance of a file.  If it does not
  2488.                     exist, a "0" is returned to the Host followed by a
  2489.                     carriage return.  If it does exist, the returned
  2490.                     text is a "1." followed by the file size (in
  2491.                     decimal).  The return sequence is terminated by a
  2492.                     carriage return.  An example of the returned text
  2493.                     could be "1.20345".
  2494.            03       Queries extended return information.  If the file
  2495.                     does not exist, a "0" is returned follwed by a
  2496.                     carriage return.  If it does exist, the text
  2497.                     returned to the Host is in the format: 
  2498.                     1.size.date.time <cr>.  An example of a return
  2499.                     statement could be "1.20345.01/02/93.03:04:30 <cr>"
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.      ---------------------------------------------------------------------
  2506.      End of RIPscrip Scene
  2507.      ---------------------------------------------------------------------
  2508.                Symbol: RIP_NO_MORE
  2509.                 Level: 0
  2510.               Command: #
  2511.             Arguments: <none>
  2512.                Format: !|#
  2513.               Example: !|#
  2514.       Uses Draw Color: NO
  2515.       Uses Line Patrn: NO
  2516.       Uses Line Thick: NO
  2517.       Uses Fill Color: NO
  2518.       Uses Fill Patrn: NO
  2519.       Uses Write Mode: NO
  2520.       Uses Font Sizes: NO
  2521.  
  2522.      This command indicates that RIPscrip commands are complete.  This
  2523.      allows the terminal program to activate Mouse Regions, or respond to
  2524.      queued up Mouse Clicks without disturbing the natural flow of the
  2525.      script transmission.
  2526.  
  2527.      For noise-immunity, the Host should transmit three or more
  2528.      RIP_NO_MORE command consecutively to make sure the message gets to
  2529.      the terminal.  The terminal should also time-out if no data is
  2530.      received for a while, and assume RIP_NO_MORE.
  2531.  
  2532.  
  2533.  
  2534.  
  2535.      =====================================================================
  2536.      ==                                                                 ==
  2537.      ==         RIPscrip Commands under development (testing)           ==
  2538.      ==                                                                 ==
  2539.      ==  These commands are subject to change at will.  They are not    ==
  2540.      ==  part of the official protocol specification.  These are just   ==
  2541.      ==  advanced warning to give you an idea what will be part of the  ==
  2542.      ==  specification in the future.                                   ==
  2543.      ==                                                                 ==
  2544.      =====================================================================
  2545.  
  2546.  
  2547.  
  2548.  
  2549.      ---------------------------------------------------------------------
  2550.      Enter "block transfer" mode with Host
  2551.      ---------------------------------------------------------------------
  2552.                Symbol: RIP_ENTER_BLOCK_MODE
  2553.                 Level: 10 (system command)
  2554.               Command: <escape>
  2555.             Arguments: proto:2 file_type:2 res:4 [filename:2] <>
  2556.                Format: !|0<escape> <proto> <file_type> <res> [filename] <>
  2557.               Example: !|0<escape>0001iconfile.icn<>
  2558.       Uses Draw Color: NO
  2559.       Uses Line Patrn: NO
  2560.       Uses Line Thick: NO
  2561.       Uses Fill Color: NO
  2562.       Uses Fill Patrn: NO
  2563.       Uses Write Mode: NO
  2564.       Uses Font Sizes: NO
  2565.  
  2566.       This command is used to auto-initiate any desired File Transfer
  2567.       Protocol.  The <filename> parameter is optional, and if omitted
  2568.       must be replaced with a "<>" parameter (end of string).  
  2569.  
  2570.       The <proto> parameter is the file transfer protocol specifier.
  2571.       Possible values, and the protocols they refer to are:
  2572.  
  2573.  
  2574.           VALUE     PROTOCOL            FILENAME REQUIRED?
  2575.           ================================================
  2576.             0       Xmodem (checksum)          Yes
  2577.             1       Xmodem (CRC)               Yes
  2578.             2       Xmodem-1K                  Yes
  2579.             3       Xmodem-1K (G)              Yes
  2580.             4       Kermit                     Yes
  2581.             5       Ymodem (batch)             No
  2582.             6       Ymodem-G                   No
  2583.             7       Zmodem (crash recovery)    No
  2584.  
  2585.      The <file_type> parameter determines what types of files are to be
  2586.      received during the block transfer.  The following values apply
  2587.      to the <file_type> parameter:
  2588.  
  2589.           VALUE     DESCRIPTION OF BLOCK TRANSFER CONTENTS
  2590.           ================================================================
  2591.             0       .RIP file sequence (display it)
  2592.             1       .RIP file sequence (store them)
  2593.             2       .ICN file sequence (store them in proper directories)
  2594.             3       .HLP file sequence (store it, and auto-load if needed)
  2595.             4       COMPOSITE DYNAMIC file sequence (batch protcols only)
  2596.             5       ACTIVE DYNAMIC file sequence (batch protcols only)
  2597.  
  2598.      Whether the <filename> is specified or not, this command must have
  2599.      a "<>" sequence after the filename (even if omitted).  Here are
  2600.      examples of how it would look with and without a filename:
  2601.  
  2602.  
  2603.           !|0B0101filename.icn<> ... With filename field (Xmodem-CRC)
  2604.           !|0B0604<> ............... w/o  filename field (Zmodem)
  2605.  
  2606.      The special <file_type> of 4 & 5 (COMPOSITE DYANAMIC file sequences)
  2607.      is somewhat different than the non-batch transfer methods.  This allows
  2608.      each file uploaded to be individually processed based on their
  2609.      file extensions.  If you use extensions other than .RIP or .ICN, then
  2610.      this mode is not available to you as the necessary files will not be
  2611.      able to be processed.  Any files that are "downloaded" from the Host
  2612.      in DYNAMIC mode are placed into the appropriate sub-directories and
  2613.      no further processing is performed.  .RIP files that are received
  2614.      are "stored" and are not played back in COMPOSITE DYNAMIC mode.  In
  2615.      ACTIVE DYNAMIC mode, they are stored and played back simultaneously.
  2616.  
  2617.      NOTE: This command must be terminated with a carriage return.  A 
  2618.            vertical bar (|) command delimiter cannot be used to separate
  2619.            this command from a subsequent one on the same line.  In other
  2620.            words, this command must be the last command on a line of text.
  2621.            The Protocol must begin on the very next line.
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.      =====================================================================
  2629.      ==          HOST COMMANDS - A TUTORIAL & REFERENCE SECTION         ==
  2630.      =====================================================================
  2631.  
  2632.      With Mouse regions, Buttons and Text Variable Query ability, you can
  2633.      control the Terminal/Paint programs and how they react with the BBS
  2634.      in many ways.  To accomplish this, there are several features of
  2635.      RIPscrip that permit you to do special actions based on different
  2636.      circumstances.  In effect, an "action language" of sorts.  The
  2637.      following sections go into the available "action language" features
  2638.      in more detail.
  2639.  
  2640.      Among the various abilities are:
  2641.  
  2642.           1. Control-Character specification
  2643.           2. Pre-defined Text Variables & User-defined text variables
  2644.           3. Pop-up pick-lists
  2645.           4. A Host Command "Template" system for added intelligence.
  2646.           5. Query text variable contents (pre-defined & user variables)
  2647.  
  2648.  
  2649.  
  2650.  
  2651.      =====================================================================
  2652.      ==                        CONTROL CHARACTERS                       ==
  2653.      =====================================================================
  2654.  
  2655.      Not all BBS'es will allow you to use control characters on their
  2656.      Service.  Regardless of that, the capability to send any Control
  2657.      Character exists in your Keystroke Macro editor.  The most
  2658.      commonly used Control Characters are:
  2659.  
  2660.         INDIVIDUAL CONTROL CHARACTERS         SPECIAL KEYSTROKES
  2661.         ===========================================================
  2662.         ^G ... Beep                           ^[[A ... Up Arrow
  2663.         ^L ... Clear Screen (Top of Form)     ^[[B ... Down Arrow
  2664.         ^M ... Carriage Return                ^[[C ... Right Arrow
  2665.         ^C ... Break (sometimes)              ^[[D ... Left Arrow
  2666.         ^H ... Backspace                      ^[[H ... Home Key
  2667.         ^[ ... Escape character               ^[[K ... End Key
  2668.         ^S ... Pause data transmission        ^[[L ... Control Home
  2669.         ^Q ... Resume data transmission
  2670.  
  2671.  
  2672.  
  2673.  
  2674.      =====================================================================
  2675.      ==                          TEXT VARIABLES                         ==
  2676.      =====================================================================
  2677.  
  2678.      A special feature of RIPaint allows it to understand what a Text
  2679.      Variable is.  A text variable is a piece of text that both RIPaint
  2680.      and RIPterm know something about.  For example, the Text Variable
  2681.      $DATE$ is known to represent the current Date on your PC.  The BBS
  2682.      may ask your PC what the values of one or more of these variables
  2683.      is, and if your Terminal knows that particular Text Variable, it
  2684.      will tell the BBS.
  2685.  
  2686.      There are two types of Text Variables.  There are built-in Text
  2687.      Variables that RIP products will ALWAYS know about.  Then there are
  2688.      also User Text Variables that can contain a variety of information
  2689.      depending on what the User entered at the time the Variable was
  2690.      created.  For example, the BBS might ask you what the contents of
  2691.      the $FULL_NAME$ variable is, and if RIPterm doesn't know, it could
  2692.      pop-up a field on the screen and ask you about it.  From then on,
  2693.      RIPterm will remember that piece of information for the next time it
  2694.      is needed by a BBS.
  2695.  
  2696.      You may use either the pre-defined Text Variables, or the User Text
  2697.      Variables at any place that allows Text Variables.
  2698.  
  2699.  
  2700.      The following is a Listing of the Pre-Defined Text Variables:
  2701.      =============================================================
  2702.  
  2703.  
  2704.      $DATE$ ... Date in short format (eg, 12/19/92)
  2705.      ----------------------------------------------
  2706.      This Text Variable will be transformed into the current Date.
  2707.      It will be displayed in the format MM/DD/YY.
  2708.  
  2709.           Example:  $DATE$ = 12/19/92
  2710.  
  2711.  
  2712.      $MONTH$ ... Month Name
  2713.      ----------------------
  2714.      This Text Variable will be transformed into the name of the
  2715.      Current Month.  It will be not abbreviated (eg, "November"
  2716.      instead of "Nov")
  2717.  
  2718.           Example:  $MONTH$ = December
  2719.  
  2720.  
  2721.      $MONTHNUM$ ... Month (in format 1-12)
  2722.      ------------------------------------
  2723.      This Text Variable is transformed into a Number representing
  2724.      the Current Month.  January=01 and December=12.  Therefore,
  2725.      the possible values for $MONTHNUM$ can range from 01-12.
  2726.  
  2727.           Example:  $MONTHNUM$ = 12
  2728.  
  2729.  
  2730.      $DAY$ ... Day in numeric form (eg, 31)
  2731.      -------------------------------------
  2732.      This Text Variable is transformed into a Number representing
  2733.      the Current Day of the month.  Possible values for this
  2734.      Variable are from 01-31.
  2735.  
  2736.           Example:  $DAY$ = 05
  2737.  
  2738.  
  2739.      $DOY$ ... Day of year (001-366)
  2740.      ------------------------------
  2741.      This Text Variable will be transformed into a Number representing
  2742.      the Day of the current Year.  Since a year contains 365 days (unless
  2743.      it is a Leap-Year where it contains 366), then the possible values
  2744.      that $DOY$ can be are 001-366.
  2745.  
  2746.           Example: $DOY$ = 214
  2747.  
  2748.  
  2749.      $YEAR$ ... 2 digit year (without century) (00-99)
  2750.      ------------------------------------------------
  2751.      This Text Variable will be transformed into a two-digit number
  2752.      representing the Current Year.
  2753.  
  2754.           Example: $YEAR$ = 92
  2755.  
  2756.  
  2757.      $FYEAR$ ... 4 digit year (with century) (0000-9999)
  2758.      --------------------------------------------------
  2759.      This Text Variable will be transformed into a four-digit number
  2760.      that represents the Current Year.
  2761.  
  2762.           Example:  $FYEAR$ = 1992
  2763.  
  2764.  
  2765.      $TIME$ ... Time in standard format (eg, 12:03:14)
  2766.      ------------------------------------------------
  2767.      This Text Variable will be transformed into the Current Time.
  2768.      The time will be in military format (hours from 00-23).
  2769.  
  2770.           Example:  $TIME$ = 18:09:33
  2771.  
  2772.  
  2773.      $HOUR$ .... Hour (format HH) - normal style
  2774.      ------------------------------------------
  2775.      This Text Variable will be transformed into a two-digit number
  2776.      representing the Current Hour.  This variable may be anywhere
  2777.      from 01-12.  This does not use Military format.
  2778.  
  2779.           Example:  $HOUR$ = 11
  2780.  
  2781.  
  2782.      $MHOUR$ ... Hour (format HH) - Military style
  2783.      --------------------------------------------
  2784.      This Text Variable will be transformed into a two-digit number
  2785.      representing the Current Hour in military format.  This variable
  2786.      may range anywhere from 00-23.
  2787.  
  2788.           Example: $MHOUR$ = 17
  2789.  
  2790.  
  2791.      $MIN$ ... Minutes (00-59)
  2792.      ------------------------
  2793.      This Text Variable will be transformed into a two-digit number
  2794.      representing the Current Minutes in the Hour.  Possible values
  2795.      for this Variable are 00-59.
  2796.  
  2797.           Example:  $MIN$ = 45
  2798.  
  2799.  
  2800.      $SEC$ ... Seconds (00-59)
  2801.      ------------------------
  2802.      This Text Variable will be transformed into a two-digit number
  2803.      representing the Current Seconds of the Minute.  Possible values
  2804.      for this Variable are 00-59.
  2805.  
  2806.           Example: $SEC$ = 59
  2807.  
  2808.  
  2809.      $AMPM$ ... Returns either AM or PM depending on time
  2810.      ---------------------------------------------------
  2811.      This Text Variable will be transformed into a two-character
  2812.      value of either "AM" or "PM" depending on what time it is.
  2813.  
  2814.           Example: $AMPM$ = PM
  2815.  
  2816.  
  2817.      $DATETIME$ ... Date & Time (eg, Sat Dec 19 14:38:50 1992)
  2818.      --------------------------------------------------------
  2819.      This Text Variable will be transformed into a combination Date
  2820.      and Time.  The format is somewhat different than standard
  2821.      Time/date notation.  The format used is:
  2822.  
  2823.        DAY-OF-WEEK   MONTH   DAY-OF-MONTH  HH:MM:SS  YEAR
  2824.  
  2825.           Example:  $DATETIME$ = Sat Dec 19 14:38:50 1992
  2826.  
  2827.  
  2828.      $TIMEZONE$ ... Time Zone or "NONE" if unknown (eg, Pacific)
  2829.      ----------------------------------------------------------
  2830.      This Text Variable will be transformed into a a word/phrase that
  2831.      describes the Current Time-Zone you are in.  This may be returned
  2832.      as anything like "PST" for Pacific Standard Time, "EST" for Eastern
  2833.      Standard Time, etc.  If the Time-Zone is not set on your PC, this
  2834.      Variable will respond with "NONE".
  2835.  
  2836.           Example: $TIMEZONE$ = PST
  2837.  
  2838.  
  2839.      $DOW$ ... Day of week fully spelled out (eg, Friday)
  2840.      ---------------------------------------------------
  2841.      This Text Variable will be transformed into the Current Day
  2842.      of the Week.  The name will be fully spelled out.  This
  2843.      Variable can be any of the values: Sunday, Monday, Tuesday,
  2844.      Wednesday, Thursday, Friday and Saturday.
  2845.  
  2846.           Example:  $DOW$ = Saturday
  2847.  
  2848.  
  2849.      $ADOW$ ... Abbreviated Day of Week (eg, Mon, Tue, etc)
  2850.      -----------------------------------------------------
  2851.      This Text Variable will be transformed into the Current Day
  2852.      of the week, in abbreviated form.  This variable may be any
  2853.      of the following values: Sun, Mon, Tue, Wed, Thu, Fri and Sat.
  2854.  
  2855.           Example:  $ADOW$ = Mon
  2856.  
  2857.  
  2858.      $WDAY$ ... Weekday where 0 is Sunday (0-6)
  2859.      -----------------------------------------
  2860.      This Text Variable will be transformed into a one-digit number
  2861.      representing the Number of the Day of the Week.  Possible values
  2862.      for this Variable are 0-6, where 0=Sunday (the first day in the
  2863.      week).
  2864.  
  2865.           Example: $WDAY$ = 2
  2866.  
  2867.  
  2868.      $WOY$ ... Week of current year 00-53; Sunday=1st Day of Week
  2869.      -----------------------------------------------------------
  2870.      This Text Variable will be transformed into a number from 00-53,
  2871.      representing the Week Number in the current year.  Even though
  2872.      there are 52 weeks in a year, a week might not begin exactly on
  2873.      the first day of the year, so a maximum value for this variable
  2874.      can be 53 under these circumstances.  For this Variable, SUNDAY
  2875.      is considered to be the first day of the week.
  2876.  
  2877.           Example:  $WOY$ = 32
  2878.  
  2879.  
  2880.      $WOYM$ ... Week of current year 00-53; Monday=1st Day of Week
  2881.      ------------------------------------------------------------
  2882.      This Text Variable will be transformed into a number from 00-53,
  2883.      representing the Week Number in the current year.  Even though
  2884.      there are 52 weeks in a year, a week might not begin exactly on
  2885.      the first day of the year, so a maximum value for this variable
  2886.      can be 53 under these circumstances.  For this Variable, MONDAY
  2887.      is considered to be the first day of the week.
  2888.  
  2889.           Example:  $WOYM$ = 32
  2890.  
  2891.  
  2892.      $RIPVER$ ... RIPterm version (eg, "RIPSCRIP014500")
  2893.      --------------------------------------------------
  2894.      This Text Variable will be transformed into a key-phrase which
  2895.      will identify a RIPterm software package.  It is designed to
  2896.      be used by a Host BBS to detect what version of RIPscrip
  2897.      graphics your Terminal can support.  When this Text Variable
  2898.      is used, it will respond back with "RIPSCRIP" followed by
  2899.      the full Version Number (eg, 01.45.00), without the periods.
  2900.  
  2901.           Example: $RIPVER$ = RIPSCRIP014500
  2902.  
  2903.  
  2904.      $STATBAR$ ... If Status Bar is on, returns YES, otherwise NO
  2905.      -----------------------------------------------------------
  2906.      This Text Variable will be transformed into a "YES" if the Status
  2907.      Bar is currently On on the Terminal.  If the Status Bar is not
  2908.      visible, then this Variable will be "NO".
  2909.  
  2910.           Example:  $STATBAR$ = YES
  2911.  
  2912.  
  2913.      $X$ ... X Mouse location   (format: XXXX)
  2914.      ----------------------------------------
  2915.      This Text Variable is for reporting the current X location of
  2916.      the Mouse to the BBS.  This could be used interactively by the
  2917.      BBS (or a game on the BBS) to deterimine the location of the
  2918.      mouse cursor.  Only the X value of the Mouse (X,Y) location is
  2919.      returned to the BBS.  The value will be 0000-9999 depending on
  2920.      what the current position is.
  2921.  
  2922.           Example:  $X$ = 0523
  2923.  
  2924.  
  2925.      $Y$ ... Y Mouse location   (format: YYYY)
  2926.      ----------------------------------------
  2927.      This Text Variable is for reporting the current Y location of
  2928.      the Mouse to the BBS.  This could be used interactively by the
  2929.      BBS (or a game on the BBS) to deterimine the location of the
  2930.      mouse cursor.  Only the Y value of the Mouse (X,Y) location is
  2931.      returned to the BBS.  The value will be 0000-9999 depending on
  2932.      what the current position is.
  2933.  
  2934.           Example:  $Y$ = 0244
  2935.  
  2936.  
  2937.      $XY$ ... X/Y Mouse Location (format: XXXX:YYYY)
  2938.      ----------------------------------------------
  2939.      This Text Variable will be transformed into a combination of
  2940.      both the X and Y locations of the Mouse Cursor.  A colon (:) is
  2941.      used to separate the two values.  Either the X or Y values may
  2942.      range from 0000-9999 depending on the current location.  The
  2943.      format that this value takes on is:  XXXX:YYYY
  2944.  
  2945.           Example:  $XY$ = 0297:0321
  2946.  
  2947.  
  2948.      $XYM$ ... X, Y & button status (format: XXXX:YYYY:LMR)
  2949.      -----------------------------------------------------
  2950.      This Text Variable will be transformed into a combination of
  2951.      the X and Y Mouse Cursor location, and a status of which
  2952.      Mouse Buttons are pressed (if any).  The format of the returned
  2953.      text is XXXX:YYYY:LMR where XXXX is the X cursor location in the
  2954.      range 0000-9999.  YYYY is the Y cursor location in the range
  2955.      0000-9999.  Finally, LMR stands for Left/Middle/Right.  If either
  2956.      of these buttons are depressed (clicked), then the corresponding
  2957.      position will contain a 1.  If a button is NOT depressed, then it
  2958.      will contain a 0.
  2959.  
  2960.           Example:  $XYM$ = 0123:0297:110
  2961.  
  2962.      This means that the (X,Y) location of the cursor is (0123,0297),
  2963.      and that the Left and Middle buttons are depressed, but that the
  2964.      Right Mouse Button is not depressed.
  2965.  
  2966.  
  2967.      $M$ ... Mouse Button Status: LMR (eg, 101)
  2968.      -----------------------------------------
  2969.      This Text Variable will be transformed into a 3-character code
  2970.      representing what the Status of each Mouse Button is.  This
  2971.      variable can work with either 2-button Mice, or 3-button Mice.
  2972.      In either event, the format of the code is LMR where L=Left,
  2973.      M=Middle (if any), and R=Right.  If any of these buttons are
  2974.      depressed (ie, clicked), then the code for that button would be
  2975.      a "1".  If the button is not depressed, it is a "0".  So, a value
  2976.      of "100" would mean that the Left Mouse Button is depressed, but
  2977.      none of the others are.
  2978.  
  2979.           Example:  $M$ = 001
  2980.  
  2981.  
  2982.      $MSTAT$ ... Mouse Status (format: XXXX:YYYY:LMR)
  2983.      ------------------------------------------------
  2984.      This Text Variable will be transformed into a "YES" if there is
  2985.      a Mouse installed on the RIPterm computer.  If no Mouse is
  2986.      installed, this variable will contain "NO".
  2987.  
  2988.           Example:  $MSTAT$ = YES
  2989.  
  2990.  
  2991.      $SBARON$ ... Turn ON the Status Line
  2992.      ------------------------------------
  2993.      This Text Variable is somewhat different than the other Text
  2994.      Variables described above.  Rather than send something back
  2995.      to the Host, it performs a specific operation - it turns ON
  2996.      the Status Line.  In this respect, it is considered an ACTIVE
  2997.      TEXT VARIABLE.  It evaluates to a null string (nothing).  Its
  2998.      sole purpose in life is to enable the Status Line.
  2999.  
  3000.           Example:  $SBARON$ = <nil>
  3001.  
  3002.  
  3003.      $SBAROFF$ ... Turn OFF the Status Line
  3004.      --------------------------------------
  3005.      This Text Variable is somewhat different than the other Text
  3006.      Variables described above.  Rather than send something back
  3007.      to the Host, it performs a specific operation - it turns OFF
  3008.      the Status Line.  In this respect, it is considered an ACTIVE
  3009.      TEXT VARIABLE.  It evaluates to a null string (nothing).  Its
  3010.      sole purpose in life is to disable the Status Line.
  3011.  
  3012.           Example:  $SBAROFF$ = <nil>
  3013.  
  3014.  
  3015.      $ETW$ ... Erase Text Window
  3016.      ---------------------------
  3017.      This Text Variable is somewhat different than the other Text
  3018.      Variables described above.  Rather than send something back
  3019.      to the Host, it performs a specific operation - it Erases the
  3020.      current Text Window (much like a Clear Screen code does).  This
  3021.      command is particularly useful in Host Commands when you click
  3022.      on a Mouse area, and after it is finished clicking, it could
  3023.      erase the text window THEN transmit the remainder of the host
  3024.      command (if any) to the BBS.
  3025.  
  3026.           Example:  $ETW$ = <nil>
  3027.  
  3028.  
  3029.      $EGW$ ... Erase Graphics Window
  3030.      -------------------------------
  3031.      This Text Variable is somewhat different than the other Text
  3032.      Variables described above.  Rather than send something back
  3033.      to the Host, it performs a specific operation - it Erases the
  3034.      current Graphics Window (much like a Reset Windows command does).
  3035.      This command is particularly useful in Host Commands when you
  3036.      click on a Mouse area, and after it is finished clicking, it
  3037.      could erase the graphics window THEN transmit the remainder of
  3038.      the host command (if any) to the BBS.
  3039.  
  3040.           Example:  $EGW$ = <nil>
  3041.  
  3042.  
  3043.      $MKILL$ ... Kill all Mouse Fields currently defined
  3044.      ---------------------------------------------------
  3045.      This Text Variable is also an "Active Text Variable" in the
  3046.      sense that it doesn't transmit anything per se to the Host.
  3047.      What it does do, is upon execution, it deletes all currently
  3048.      defined Mouse Fields exactly like the RIP_KILL_MOUSE_FIELDS
  3049.      does.  The net benefit of this is that when the user clicks
  3050.      on a Mouse Button, the Mouse Fields are removed, but the
  3051.      graphics remain on the screen so that the fields could be
  3052.      subsequently re-defined quickly and easily without having to
  3053.      re-transmit an identical menu over again.
  3054.  
  3055.           Example:  $MKILL$ = <nil>
  3056.  
  3057.  
  3058.      $BEEP$ ... Beeps the terminal (like a CTRL-G does)
  3059.      --------------------------------------------------
  3060.      This command is an Active Text Variable.  It's sole purpose
  3061.      in life is to issue a Beep to the Terminal, thus producing
  3062.      a CTRL-G sound.
  3063.  
  3064.           Example:  $BEEP$ = <nil>
  3065.  
  3066.  
  3067.      $BLIP$ ... Makes a short "blipping" sound (like a Barrier)
  3068.      ----------------------------------------------------------
  3069.      This Active Text Variable is much like the BEEP variable,
  3070.      except that the sound produced is different.  It produces
  3071.      a sound more akin to a "barrier" sound; something that 
  3072.      sounds like you're running into a wall or something to that
  3073.      effect.
  3074.  
  3075.           Example:  $BLIP$ = <nil>
  3076.  
  3077.  
  3078.      $MUSIC$ ... Makes a musical (cheerful) sound
  3079.      --------------------------------------------
  3080.      This Active Text Variable also produces an Audio result.  The
  3081.      sound that is generated is a cheerful sound, representing 
  3082.      some kind of success.  The sound is exactly the same as the
  3083.      Sound you would hear when you receive a successful download,
  3084.      or when you achieve a connection when dialing the modem in
  3085.      RIPterm.
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.      =====================================================================
  3092.      ==                           POP-UP LISTS                          ==
  3093.      =====================================================================
  3094.  
  3095.      Any place that you can use a Text Variable, you can take advantage
  3096.      of a unique feature of RIPscrip - Popup Pick-Lists.  A Popup Pick-
  3097.      List is simply a list that pops up allowing you to choose from one
  3098.      of several available values.  Whichever entry in the list you choose
  3099.      will be inserted into your Keystroke Macro in place of the List
  3100.      Definition.
  3101.  
  3102.      In order to use Popup Pick-Lists, you must define the List in the
  3103.      text of your Host Command.
  3104.  
  3105.      A List is created by putting the special List instructions inside of
  3106.      two parenthesis (( and )).  The list instructions consist of an
  3107.      optional Question, followed by one or more entries to put in the
  3108.      List.  For example, ((Send Email to?::Sysop,Cosysop,Joe)) says to
  3109.      Pop-Up a list asking you "Send Email to?", giving you the choices of
  3110.      "Sysop", "Cosysop", and "Joe".
  3111.  
  3112.      By default, if you hit <ESCAPE> instead of picking an entry in the
  3113.      list, then nothing will be inserted into the text of your Command.
  3114.      You can indicate that the user MUST pick an entry by puttin an
  3115.      asterisk (*) at the beginning of the question.  For example, 
  3116.      ((*Send Mail to?::Sysop,Joe)).  This would make it so that the User
  3117.      MUST choose either SYSOP or JOE.
  3118.  
  3119.      In the previous examples, SYSOP, COSYSOP and JOE are the actual text
  3120.      responses that are inserted into your Macros.  These commands are
  3121.      also the same things that are displayed in the Listing.  If you want
  3122.      to use something else instead of the actual "return text", you can.
  3123.      When you enter the List Entry, add a @description to the end of it.
  3124.  
  3125.  
  3126.         For example, ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe))
  3127.  
  3128.  
  3129.      One final feature of Popup Pick-Lists allow you to specify a hotkey
  3130.      for each entry in the List.  For example, if you wanted the first
  3131.      character of each entry to be hilighted (thus allowing you to select
  3132.      that character to activate the entry), simply put a tilda (~) or an
  3133.      underline (_) before and after the keystroke.  For example "_S_ysop"
  3134.      would hilight the "S" in "Sysop".  You can hilight more than one
  3135.      character, but only the first one will be the active hotkey.  If you
  3136.      omit the second tilda or underline, then the remainder of the
  3137.      description will be hilighted.
  3138.  
  3139.         NOTE: If you use a Tilda or an Underline in the actual Text
  3140.               Response command (not the description), then those
  3141.               characters will be automatically inserted into your
  3142.               Macro when it gets transmitted to the BBS.  This is
  3143.               probably not what you would want to do.  Bottom line,
  3144.               only use Hotkey features on List Entries where you
  3145.               specify a Description!
  3146.    
  3147.               If you do not specify a Question, then the List will
  3148.               ask you: 
  3149.           
  3150.        
  3151.                   "Choose one of the following:"
  3152.    
  3153.    
  3154.               You may specify up to twenty List Entries for any
  3155.               one list.
  3156.  
  3157.  
  3158.      Examples:
  3159.  
  3160.        ((Send E-Mail to?::Sysop,Joe,Mike))
  3161.        ((*Send EMail to?::Sysop@The Head Honcho,Joe,Mike@My Brother))
  3162.        ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother))
  3163.        ((Sysop,Joe,Mike,George))
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.      =====================================================================
  3170.      ==                     HOST COMMAND "TEMPLATES"                    ==
  3171.      =====================================================================
  3172.  
  3173.      This feature is somewhat complex in nature, but ultimately powerful
  3174.      in the long run when creating interactive mouse-driven GUI systems.
  3175.  
  3176.      Often times you might want a Button on your screen to do one thing
  3177.      in one situation, but to do something completely different in
  3178.      another situation.  In the past, this required having a separate
  3179.      menu file for each different function that this Button needs.  This
  3180.      cumbersome method is "history" with Command Templates.
  3181.  
  3182.      Command Templates are probably best described with a brief example.
  3183.      Let's say that you have a menu screen for reading and writing 
  3184.      messages in your public message forums.  On this menu, you can have
  3185.      buttons for each forum on your system, and at the same time have
  3186.      buttons for READ, WRITE, ERASE, MODIFY, etc.  Now, how can you make
  3187.      the READ/WRITE/etc buttons work differently for each Forum?
  3188.  
  3189.  
  3190.                                    Templates!
  3191.  
  3192.  
  3193.      To further refine our example, let's say that if you click on the
  3194.      button for Forum #1, it should send the command "S FORUM1" to the
  3195.      host to select that forum.  After that, simply clicking on the
  3196.      READ or WRITE buttons will read through the current section.  But,
  3197.      what if you want to interactively move about on the menu quickly?
  3198.      Make each of the Forum selection buttons define a template.  Each
  3199.      template will instruct RIPscrip how to process the other Buttons.
  3200.  
  3201.      In the above example, the Forum #1 button would define a template
  3202.      like this:
  3203.  
  3204.  
  3205.                                  S FORUM1 $?$^m
  3206.  
  3207.  
  3208.      This Template will return "S FORUM1" followed by the Host Command
  3209.      for whichever button is clicked, followed by a carriage return.
  3210.      The special text variable $?$ is only used in Command Templates,
  3211.      and is used to indicate "insert the text into the template here".
  3212.      It references the text of some other button that was clicked that
  3213.      is stuffing it's data INTO this template.
  3214.  
  3215.  
  3216.      CHARACTERISTICS OF TEMPLATES
  3217.      ----------------------------
  3218.         Before you can actually go about defining templates, you
  3219.         need to know how they work, interact and how other functions
  3220.         interact with templates.
  3221.  
  3222.         You are allowed up to 36 different templates, each of which
  3223.         can be different and can all be active at the same time.  Each
  3224.         of the 36 templates correspond to a Button Group (see the 
  3225.         Button Command).  Templates can be defined and/or activated
  3226.         in any order.  In other words, you can have a template #1, 5
  3227.         13 and 32, but none of the others defined.  Templates remain
  3228.         defined until re-defined by another template.
  3229.  
  3230.  
  3231.      DEFINING A TEMPLATE
  3232.      -------------------
  3233.         To create a template, when asked for a Host Command, simply
  3234.         type in the Template similar to the following:
  3235.  
  3236.  
  3237.                [5:]S FORUM1 $?$^m
  3238.  
  3239.  
  3240.         The [5:] at the beginning of the command indicates that you
  3241.         wish to create template #5 with the following text as the
  3242.         template.  Remember, a $?$ is considered a "macro" that will
  3243.         insert some text into this template from some other source.
  3244.         Valid template numbers are 0-9, A-Z.  So, with this in mind,
  3245.         all of the template definitions are valid:
  3246.  
  3247.           
  3248.                [0:]S FORUM1 $?$^m
  3249.                [9:]S FORUM2 $?$^m
  3250.                [G:]S FORUM3 $?$^m
  3251.  
  3252.  
  3253.      USING TEMPLATES
  3254.      ---------------
  3255.         When you want to make a button "feed its command" into a
  3256.         template, you do so in a format similar to defining a
  3257.         Template, but with a subtle difference.  Don't include
  3258.         the colon (:) in the template reference.  An example of
  3259.         this would be the following:
  3260.  
  3261.  
  3262.                [0]HELLO
  3263.  
  3264.  
  3265.         This says, take the text "HELLO" and feed it into template
  3266.         number 0, and send the final result to the BBS.  Note how
  3267.         simple it is to create and reference templates by either
  3268.         using a colon or omitting it.
  3269.  
  3270.         If you do not specify a Template reference in the format
  3271.         [#] at the beginning of your Host Command, it will be
  3272.         considered to be a "normal Host Command" that does not
  3273.         get stuffed into any templates.  For completeness, you
  3274.         may specify []HELLO to send the word "HELLO" to the BBS
  3275.         without going through any templates (a "null" template).
  3276.         So in other words, using a [] or using nothing at all is
  3277.         the same thing, don't use any templates for this Host
  3278.         command.
  3279.  
  3280.  
  3281.      CHAINING ONE TEMPLATE RESPONSE INTO ANOTHER (TEMPLATE CHAINING)
  3282.      ---------------------------------------------------------------
  3283.         In the preceding examples we showed how you can feed the
  3284.         Host Command of one button through a single Template
  3285.         definition.  This is the "simplest case" of template
  3286.         processing.  As part of the "big picture" of templates,
  3287.         you can actually "chain" the input of one template into
  3288.         another template, into another, so on and so forth and
  3289.         then transmit the result of all composite template stuffing
  3290.         to the Host as one big command.  After all is said and done
  3291.         with template processing, the text buffer sent to the host
  3292.         can be anywhere from 0-4095 bytes in length.
  3293.  
  3294.         To chain one template into another, follow a format similar
  3295.         to the following:
  3296.  
  3297.          
  3298.                [0372]HELLO
  3299.  
  3300.  
  3301.         This will feed the word "HELLO" into template #0, then the
  3302.         result into template #3, then that result into template #7,
  3303.         then finally the result will be stuffed into Template #2.
  3304.         The final result will be then transmitted to the BBS.
  3305.  
  3306.         You may specify from 0-36 different templates in any one
  3307.         chaining operations.  You MAY use the same template more
  3308.         than once in the same chain, like the following:
  3309.  
  3310.  
  3311.                [0370]HELLO
  3312.  
  3313.  
  3314.         Note, that template #0 is used twice, both at the beginning
  3315.         and the end of the processing.  This feature, potentially
  3316.         dangerous, is provided for completeness and flexibility.
  3317.  
  3318.  
  3319.      EMBEDDED TEMPLATES
  3320.      ------------------
  3321.         You can embed the contents of one Template into another
  3322.         template (or into a Host Command) by using the special
  3323.         Text Variable $?x$ where "x" is the Template number to
  3324.         insert.  This command functions much like the insert-text
  3325.         variable $?$ does, but gives you a great deal more power
  3326.         and flexibility.
  3327.  
  3328.         If you specify to embed one template inside another, the
  3329.         embedded template can contain text variables, pick-lists
  3330.         and other such things.  It can even have another embedded
  3331.         template in it as well, but that sub-embedded template
  3332.         cannot have ANY text variables, or any special commands,
  3333.         not even control characters!
  3334.  
  3335.         To sum it up, an embedded template can have anything you
  3336.         want in it, including other embedded templates.  All
  3337.         text variables in an embedded template are expanded, as
  3338.         are pick lists, control characters and the like.  If you
  3339.         have an embedded template INSIDE an embedded template,
  3340.         the deepest embedded template will have NO text variable
  3341.         processing done on it - ie, the text is sent to the
  3342.         host verbatim, exactly as it appears in the template.
  3343.  
  3344.         If a template that is referenced is not yet defined, the
  3345.         template embed command will be skipped (ie, blank) providing
  3346.         that the embedded template doesn't refer to a Radio Group.
  3347.         Radio Groups are "dependencies" in this manner.  Anything
  3348.         that tries to embed a Template from a Radio Group will
  3349.         not be processed if a template in that area hasn't been
  3350.         defined yet.  Embedded templates from Checkbox Groups can
  3351.         be skipped if none of the check-boxes are active.
  3352.  
  3353.  
  3354.      TEXT VARIABLES, PICK-LISTS AND CONTROL CHARACTERS IN TEMPLATES
  3355.      --------------------------------------------------------------
  3356.         You may use Text Variables, Pick-Lists and Control Characters
  3357.         anywhere in any template definition, or reference.  You are
  3358.         limited such that, a text variable is translated to its
  3359.         real value when the template is being processed, not after
  3360.         all templates are processed.  The net result of this is,
  3361.         you cannot use one template to construct another template's
  3362.         pick-list, text variables, or the such.
  3363.  
  3364.         In other words, you cannot "nest" text variable definitions,
  3365.         pick lists, or control characters.  You can have these
  3366.         commands in any or all templates used in a given template
  3367.         chain, but they are independent of each other.
  3368.  
  3369.  
  3370.      EXAMPLES OF SOME TEMPLATE-CHAINS
  3371.      --------------------------------
  3372.         Below are several examples of different template setups.
  3373.         These are intended to give you ideas on how templates
  3374.         may be used:
  3375.  
  3376.           Example #1:
  3377.  
  3378.             [0:]D $?$ Z^m       ... Used to download a file with Zmodem
  3379.             [1:]D $?$ X^m       ... Used to download a file with Xmodem
  3380.  
  3381.             [0]FILENAME.ZIP     ... Use this with #0 to download Zmodem
  3382.             [1]FILENAME.ZIP     ... Use this with #1 to download Xmodem
  3383.  
  3384.             In this example, template #0 is used for downloading with
  3385.             Zmodem.  Template #1 is for downloading with Xmodem.
  3386.             Depending on which FILENAME.ZIP button you click on, you
  3387.             might download it with one protocol or with another.  It
  3388.             all lies on which template you reference.  The text
  3389.             transmitted to the BBS if you clicked on the buttons could
  3390.             be either:
  3391.  
  3392.                     D FILENAME.ZIP Z^m
  3393.               or,   D FILENAME.ZIP X^m
  3394.  
  3395.  
  3396.           Example #2:
  3397.  
  3398.             [0:]D $?$           ... Make this the "DOWNLOAD NOW" button
  3399.  
  3400.             [1:]$?$ X^m         ... Radio Button #1   (X-Modem)
  3401.             [1:]$?$ Y^m         ... Radio Button #2   (Y-Modem)
  3402.             [1:]$?$ B^m         ... Radio Button #3   (Y-Modem Batch)
  3403.             [1:]$?$ Z^m         ... Radio Button #4   (Z-Modem)
  3404.  
  3405.             [01]FILENUM1.ZIP    ... Button to download file #1
  3406.             [01]FILENUM2.ZIP    ... Button to download file #2
  3407.             [01]FILENUM3.ZIP    ... Button to download file #3
  3408.  
  3409.             This example is a bit more involved.  It brings the concept
  3410.             of "radio buttons" into the picture.  This is something
  3411.             that is part of the Button command.  A Radio button is
  3412.             like having a list of options on your screen, only one
  3413.             of which can be active at any one time.  When using
  3414.             templates with Radio buttons, you can quickly and elegantly
  3415.             define a menu that can do one thing in one mode, or
  3416.             something totally different in another mode.  An example
  3417.             of the above menu might be as follows:
  3418.  
  3419.  
  3420.                  Protocols:                Download which file?     
  3421.                     __                        __
  3422.                    |\/|                      |  |
  3423.                    |/\| X-Modem              |  | File #1
  3424.                     --                        --
  3425.                     __                        __
  3426.                    |  |                      |\/|
  3427.                    |  | Y-Modem              |/\| File #2
  3428.                     --                        -- 
  3429.                     __                        __
  3430.                    |  |                      |  |
  3431.                    |  | Y-Modem (batch)      |  | File #3
  3432.                     --                        --  
  3433.                     __
  3434.                    |  |
  3435.                    |  | Z-Modem         _______________________
  3436.                     --                 |                       |
  3437.                                        |  BEGIN DOWNLOAD NOW!  |
  3438.                                        |_______________________|
  3439.  
  3440.  
  3441.      MORE ABOUT TEMPLATES
  3442.      --------------------
  3443.         When you use the $?$ text variable inside a template definition,
  3444.         you are not limited to using it only once.  In fact, you can use
  3445.         it as many times in your template definition as you wish.  This
  3446.         can be useful under many circumstances where the user might have
  3447.         to enter the same thing twice.
  3448.  
  3449.         In the preceding example #2, a group of Radio Buttons was used
  3450.         on the right side of the screen to determine which file should
  3451.         be downloaded.  In that example, there was no ability to specify
  3452.         an arbitrary filename to download.  You were only allowed to 
  3453.         download one of three given files.  What would be perfect, would
  3454.         be to have the ability to pop-up a question to the user asking
  3455.         what filename they wanted.  The solution is easy, insert a
  3456.         text-variable that hasn't been defined yet!  To illustrate, the
  3457.         above example could be modified to accomodate this as follows:
  3458.  
  3459.             [0:]D $?$           ... Make this the "DOWNLOAD NOW" button
  3460.  
  3461.             [1:]$?$ X           ... Radio Button #1   (X-Modem)
  3462.             [1:]$?$ Y           ... Radio Button #2   (Y-Modem)
  3463.             [1:]$?$ B           ... Radio Button #3   (Y-Modem Batch)
  3464.             [1:]$?$ Z           ... Radio Button #4   (Z-Modem)
  3465.  
  3466.             [01]FILENUM1.ZIP    ... Button to download file #1
  3467.             [01]FILENUM2.ZIP    ... Button to download file #2
  3468.             [01]FILENUM3.ZIP    ... Button to download file #3
  3469.             [01]$FILENAME$      ... Button to download ANY file
  3470.  
  3471.         The screen might appear something like this:
  3472.  
  3473.                  Protocols:                Download which file?     
  3474.                     __                        __
  3475.                    |\/|                      |  |
  3476.                    |/\| X-Modem              |  | File #1
  3477.                     --                        --
  3478.                     __                        __
  3479.                    |  |                      |\/|
  3480.                    |  | Y-Modem              |/\| File #2
  3481.                     --                        -- 
  3482.                     __                        __
  3483.                    |  |                      |  |
  3484.                    |  | Y-Modem (batch)      |  | File #3
  3485.                     --                        --  
  3486.                     __                        __
  3487.                    |  |                      |  |
  3488.                    |  | Z-Modem              |  | Enter Filename
  3489.                     --                        -- 
  3490.                                        
  3491.                                _______________________         
  3492.                               |                       |
  3493.                               |  BEGIN DOWNLOAD NOW!  |
  3494.                               |_______________________|
  3495.         
  3496.  
  3497.         Note the addition of the "Enter Filename" button.  If the user
  3498.         clicked on that button, it would first try to replace $FILENAME$
  3499.         with a text variable.  It will find that such a variable does
  3500.         not exist, and will then pop-up the following question on the
  3501.         screen:
  3502.  
  3503.                        _____________________________ 
  3504.                       |                             |
  3505.                       |       Enter "FILENAME"      |
  3506.                       |   _______________________   |
  3507.                       |  |                       |  |
  3508.                       |  |_______________________|  |
  3509.                       |                             |
  3510.                       |_____________________________|
  3511.  
  3512.  
  3513.         If the user typed in "DEMOFILE.TXT", then that filename is
  3514.         inserted where $FILENAME$ was located, then it is piped through
  3515.         template #0, resulting in:
  3516.         
  3517.         
  3518.                     D DEMOFILE.TXT
  3519.                    
  3520.                 
  3521.         The result of that is then stuffed through Template #1 which
  3522.         gives the following return string sent to the BBS:
  3523.  
  3524.  
  3525.                     D DEMOFILE.TXT Z^m
  3526.  
  3527.  
  3528.         This is only an example, your mileage may vary.
  3529.  
  3530.  
  3531.  
  3532.  
  3533.      =====================================================================
  3534.      ==                TEXT VARIABLE CREATION, AND QUERY                ==
  3535.      =====================================================================
  3536.  
  3537.      As mentioned in preceding sections, Text Variables were described
  3538.      as either "pre-defined" variables, or as "User Variables".  Pre-
  3539.      defined variables are variables that RIPscrip products know things
  3540.      about "out of the box".  They will always know what the variables
  3541.      mean, from the day you install them.  User Variables on the other
  3542.      hand, are variables that you, the user of RIPscrip products define,
  3543.      and teach the system information.
  3544.  
  3545.  
  3546.      WHAT ARE USER VARIABLES?
  3547.      ------------------------
  3548.         A User Variable is a Text Variable that RIPscrip doesn't
  3549.         already know exists.  They are custom-defined text variables
  3550.         that contain information that the RIPterm user will fill-in.
  3551.         If a variable already contains information, a BBS will be auto-
  3552.         matically told [IF TOLD TO DO SO] what that variable contains
  3553.         without the user having to intervene (ie, transparent informa-
  3554.         tion exchange).
  3555.  
  3556.            Examples of Text Variables might be:
  3557.  
  3558.                $FULL_NAME$    ... What is your full name?
  3559.                $COMPANY_NAME$ ... What company do you work for?
  3560.                $AGE?          ... How old are you?
  3561.                $DATEOFBIRTH$  ... What is your Date of Birth?
  3562.                $PHONENUMBER$  ... What is your Day-time phone number?
  3563.  
  3564.         User Variables will "keep track" of these responses for you,
  3565.         on the Terminal program end.  You can tell the Terminal to
  3566.         store these values "permanently" in a disk-file, or they may
  3567.         be active only during the current online session, or they
  3568.         may be defined as "temporary" where they are not stored for
  3569.         more than a brief moment.  
  3570.  
  3571.         Note, this ability is configurable so that information exchange
  3572.         can be either interactive, or automatic.  Automatic transfer
  3573.         of information does NOT prompt the user with the information
  3574.         unless the variable has not yet been defined.  If it has not
  3575.         been defined, a pop-up question will appear asking the user
  3576.         a particular question, thus defining the text variable.  
  3577.         
  3578.         If the exchange is "interactive", the data is displayed in a
  3579.         pop-up editor box, asking you if the information is correct.
  3580.         If it is, simply tap <ENTER> and the retrieved information is
  3581.         sent to the BBS for you.  If it is not correct, or it has not
  3582.         been created yet, just type it in and tap <ENTER> and it will 
  3583.         be saved automatically, and sent to the BBS all at once.
  3584.  
  3585.  
  3586.      HOW CAN USER VARIABLES BE IMPORTANT?
  3587.      ------------------------------------
  3588.         Let's take an example.  Let's say you are a System Operator
  3589.         of a large RIPscrip BBS.  As you have read, RIPscrip can take
  3590.         advantage of "database like" ability on the terminal-end of
  3591.         the communication.  If you can alter your BBS to ask questions
  3592.         with RIPscrip "text variables" built in, you can have the
  3593.         terminal calling your system automatically fill-in questionaires
  3594.         on your system.  Imagine if a user could "sign-up" on your BBS
  3595.         without having to type more than a single keystroke (ie, "YES,
  3596.         this information is correct").  With User Text Variables, you
  3597.         can do this very thing.
  3598.  
  3599.  
  3600.      CREATING USER VARIABLES
  3601.      -----------------------
  3602.         There are two ways of defining User Text Variables in RIPaint.
  3603.         You can use either "Define Text Variable" commands, or you
  3604.         can use Text Variable Queries, as described in the next
  3605.         section.
  3606.  
  3607.  
  3608.      DEFINING TEXT VARIABLES
  3609.      -----------------------
  3610.         The RIPscrip command "Define Text Variable" is by definition,
  3611.         an interactive command with the User.  The RIPscrip command
  3612.         will attempt to define a "User Variable".  This Variable is
  3613.         some piece of information that the System Operator deems 
  3614.         important.  You may specify a question, a default response,
  3615.         and how many characters long the response may be.
  3616.  
  3617.         Once the "define command" has been sent to the Terminal, it
  3618.         [the terminal] pops up an appropriate question box on the
  3619.         User's screen asking him the desired question that should be
  3620.         saved to a particular Text Variable.  If you did not specify
  3621.         a question, a suitable "default" question will be displayed.
  3622.  
  3623.         Once the User has entered his response, it is recorded and
  3624.         saved.  How long it is saved depends on how the BBS told
  3625.         the terminal.  The BBS can tell the terminal "save this
  3626.         on your hard disk forever".  The BBS may also tell the
  3627.         terminal, "don't save this to disk, but remember this value
  3628.         until your connection with our BBS is lost".  You also have
  3629.         the option of saying, "don't remember this value at all,
  3630.         just simply pop-up a question on-screen, and send the value
  3631.         to me NOW - ie, don't save it at all - just enter it and send
  3632.         it to the BBS).
  3633.  
  3634.  
  3635.      QUERYING TEXT VARIABLES
  3636.      -----------------------
  3637.         Now that you know how to define information on the terminal,
  3638.         you need to know the last method of asking the terminal
  3639.         about text variables.  This feature is called "data query".
  3640.         
  3641.         Data Query is a generic "query" command that can ask the
  3642.         terminal one or more questions, and tell it how to transmit
  3643.         the information back to the host.  This command is for use
  3644.         in non-button situations where you do not want to wait until
  3645.         the user clicks on a button to get your data back.
  3646.  
  3647.         A Data Query is actually a special RIPscrip command that can
  3648.         be used to ask the contents of one or more Text Variables.
  3649.  
  3650.  
  3651.      EXAMPLES OF TEXT VARIABLE QUERY
  3652.      -------------------------------
  3653.        Let's take a simple example.  Let's say that you wanted to ask
  3654.        the Terminal program some address information.  You could do
  3655.        so with the following query (remember, the query also tells
  3656.        the terminal HOW to send the data back to the BBS):
  3657.  
  3658.           
  3659.           $FULL_NAME$^m$COMPANY$^m$STREET_ADDR$^m$CITY$, $STATE$ $ZIP^m
  3660.  
  3661.  
  3662.        This would query the terminal the contents of 6 text variables,
  3663.        and format them in a manner similar to any normal address on
  3664.        an envelope.  The results of this query might send the following
  3665.        back to the host (again, your mileage may vary):
  3666.  
  3667.  
  3668.           Jeff Reeder
  3669.           TeleGrafix Communications, Inc.
  3670.           16458 Bolsa Chica #15
  3671.           Huntington Beach, CA 92649
  3672.  
  3673.  
  3674.        If a text variable is queried, and it has not been defined yet,
  3675.        a pop-up question will appear asking the user to fill-in the
  3676.        information.
  3677.  
  3678.  
  3679.